Matrix Builds and Parallel Jobs

# CHAPTER 13

Matrix Builds and Parallel Jobs #

1. Introduction #

2. Learning Objectives #

• Define the concept of a Matrix Strategy in GitHub Actions.

• Configure a workflow to test code across multiple software versions automatically.

• Understand how GitHub dynamically spins up parallel runners for a matrix.

• Utilize the fail-fast configuration option to optimize compute time.

• Identify scenarios where matrix builds are architecturally necessary.

3. Beginner-Friendly Explanation #

• The Old Way (Sequential Testing): You put the tires on a Honda and drive it in the rain. Then you take them off, put them on a Ford, and drive it in the snow. Then you put them on a Toyota and drive it in the mud. It takes weeks to finish testing.

• The Matrix Way (Parallel Testing): You write a single instruction manual: "Drive the car through the obstacle course." You hand this manual to three different drivers, sitting in a Honda, a Ford, and a Toyota, experiencing Rain, Snow, and Mud simultaneously. They all execute the test at the exact same time. You get all the results in 10 minutes.

4. The strategy.matrix Syntax #

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ['8.1', '8.2', '8.3']

In this simple example, GitHub takes this *single* job definition and dynamically executes it *three* times in parallel.

5. Multi-Dimensional Matrices #

jobs:
  test:
    # Instead of hardcoding 'ubuntu-latest', we use the matrix variable!
    runs-on: ${{ matrix.os }} 
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [18.x, 20.x]

GitHub calculates the combinations (2 OS types x 2 Node versions = 4 Jobs). It will instantly spin up 4 separate cloud servers and run them all at the exact same time!

6. Mini Project: Test App on Multiple PHP Versions #

Step-by-Step Walkthrough:

1. 1. Create .github/workflows/matrix-demo.yml.

1. 2. Paste the following declarative code:

name: Matrix Compatibility Test
on: [pull_request]

jobs:
  compatibility-test:
    runs-on: ubuntu-latest
    strategy:
      # If one job fails, do NOT cancel the others. Let them finish to see the full results.
      fail-fast: false 
      matrix:
        php-version: ['8.0', '8.1', '8.2']

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      # Here we dynamically inject the PHP version from the matrix!
      - name: Setup PHP ${{ matrix.php-version }}
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}

      - name: Display PHP Version
        run: php -v
        
      - name: Run Tests
        run: echo "Pretending to run phpunit..."

1. 3. Commit the code and open a Pull Request.

1. 4. Observation: Look at the Actions tab. You will not see one job named compatibility-test. You will see a dropdown containing three uniquely named jobs: compatibility-test (8.0), compatibility-test (8.1), and compatibility-test (8.2). All three passed in parallel!

7. Real-World Scenarios #

8. Best Practices #

• Use fail-fast: false for Compatibility: By default, if a matrix creates 5 jobs, and Job 1 fails, GitHub instantly cancels the other 4 jobs to save compute time (fail-fast: true). This is bad for compatibility testing! If it fails on Windows, you still want to know if it passes on Linux. Always set fail-fast: false when your goal is to map out a compatibility grid.

9. Security Recommendations #

• Billing Awareness: Matrix builds consume billing minutes exponentially. If you define 3 OS types, 3 language versions, and 3 database types, GitHub will spin up 27 servers. If each test takes 10 minutes, you just consumed 270 billing minutes for a single commit. Be highly strategic about which combinations are actually necessary to test.

10. Troubleshooting Tips #

• Excluding Combinations: Sometimes a specific combination doesn't make sense (e.g., trying to test Internet Explorer on macOS). You can explicitly remove specific combinations from the matrix using the exclude: keyword within the strategy block to save time and prevent guaranteed errors.

11. Exercises #

1. 1. Explain how a matrix strategy optimizes developer feedback time compared to running tests sequentially in a single job.

1. 2. In what scenario would you explicitly change the default fail-fast: true setting to false?

12. FAQs #

13. Interview Questions #

• Q: You are developing a Python library that must support Python 3.9, 3.10, and 3.11 across Windows and Linux. Architect the YAML strategy block required to achieve this testing matrix in GitHub Actions.

• Q: Explain the exponential billing risks associated with multi-dimensional matrix builds. How can the exclude keyword be utilized to optimize resource consumption?

14. Summary #

15. Next Chapter Recommendation #