GitHub Actions Matrix Builds Guide

GitHub Actions Matrix Builds Guide | Generated by AI

Home 2025.10

It sounds like you’re asking about using GitHub Actions matrix builds to run tests in parallel, and how to use the fail-fast option in a matrix strategy. Let me break it down for you.

Matrix Builds in GitHub Actions

The matrix strategy allows you to run the same job in parallel with different parameters—for example, testing across multiple Python or Node versions, or on different operating systems.

A minimal example:

name: CI

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, 3.10]
        os: [ubuntu-latest, windows-latest]
      fail-fast: false
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: $
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

Key Points

matrix: Defines the variables to create job combinations.
The above example runs tests for all combinations of (python-version, os).
Parallel execution: Each job generated by the matrix runs in parallel by default.
fail-fast:
- Default is true. This means if one job fails, the rest of the matrix jobs are canceled.
- Set fail-fast: false if you want all matrix jobs to continue running, even if one fails.
Example:
```
strategy:
  matrix:
    node: [14, 16, 18]
  fail-fast: false
```

Limiting total jobs: You can exclude some combinations:

strategy:
  matrix:
    python-version: [3.8, 3.9, 3.10]
    os: [ubuntu-latest, windows-latest]
  exclude:
    - python-version: 3.8
      os: windows-latest

Running Tests in Parallel

Each matrix job runs in parallel on its own runner, so you don’t need to do anything special.
Inside each job, if you want parallel test execution (e.g., pytest -n auto), you can add that at the test command level.

Example:

- name: Run pytest in parallel
  run: pytest -n auto

✅ Summary:

Use strategy.matrix to define different parameter combinations.
Set fail-fast: false if you want all matrix jobs to run even if one fails.
Matrix jobs run in parallel automatically.
For faster runtime inside each job, use test framework parallelization (e.g. pytest-xdist).

Would you like me to show you a real example for running Node/JavaScript tests with matrix (multiple Node versions, fail-fast: false, tests parallelized with npm test)?

Back

openai/gpt-5

Donate