Use continue-on-error in GitHub Actions Matrix Jobs

Let experimental matrix entries fail without failing the workflow run. Combine continue-on-error with fail-fast, and choose job-level or step-level placement.

Published

At a glance

Last reviewed
Reading time
3 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

Set continue-on-error: ${{ matrix.experimental }} at the job level and mark the entries that may fail with experimental: true in include. Those entries can fail without failing the workflow run or affecting the other matrix jobs. Entries with experimental: false still fail the run normally.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true
    steps:
      - run: echo "Testing version ${{ matrix.version }}"

continue-on-error is evaluated once per matrix combination. Versions 6, 7 and 8 resolve it to false. The included version 9 job resolves it to true.

How fail-fast and continue-on-error interact

strategy.fail-fast applies to the whole matrix. When it is true (the default), GitHub cancels all in-progress and queued matrix jobs as soon as any job with continue-on-error: false fails. For a related walkthrough, see Run GitHub Actions Jobs Only When Specific Files Change.

continue-on-error applies to a single job. If a job with continue-on-error: true fails, the other jobs in the matrix are not affected.

In the example above, a failure in version 6, 7 or 8 cancels the remaining in-progress and queued jobs, including version 9. A failure in version 9 cancels nothing.

Set fail-fast: false if you want every combination to run to completion regardless of failures. In that case continue-on-error only decides whether a failed job fails the workflow run.

Mark experimental entries on an existing matrix

You can also add an experimental combination on top of a multi-axis matrix. This variant lets the Node 15 job on Ubuntu fail without failing the run, and lets all other jobs finish even if one fails:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix:
        node: [18, 20]
        os: [macos-latest, ubuntu-latest]
        experimental: [false]
        include:
          - node: 22
            os: ubuntu-latest
            experimental: true
    steps:
      - run: echo "Node ${{ matrix.node }} on ${{ matrix.os }}"

The experimental: [false] axis gives every generated combination a value, so the expression never evaluates against a missing key. The include entry does not match an existing combination, so it is added as an extra job.

Job-level vs step-level placement

Job-level continue-on-error: true prevents a workflow run from failing when that job fails. The job still stops at its first failing step.

name: Job-level continue-on-error
on: push
jobs:
  optional-tests:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - run: exit 1

Step-level continue-on-error: true prevents the job from failing when that step fails. The job proceeds to the next step.

name: Step-level continue-on-error
on: push
jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - run: exit 1
        continue-on-error: true
      - run: echo "Runs because the previous step was allowed to fail"

Use job-level placement when a whole matrix variant is optional. Use step-level placement when one step, such as a lint or cleanup step, is non-critical but the rest of the job must run.

Run a final job after the matrix

A downstream job that must run even when matrix entries fail needs if: always(). Without it, a failed or cancelled needs job skips the dependent job.

name: matrix-collect
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix:
        node-version: [18, 20]
        experimental: [false]
        include:
          - node-version: 22
            experimental: true
    steps:
      - run: echo "Testing on Node ${{ matrix.node-version }}"

  report:
    runs-on: ubuntu-latest
    needs: [test]
    if: always()
    steps:
      - name: Report matrix result
        env:
          TEST_RESULT: ${{ needs.test.result }}
        run: echo "test result is $TEST_RESULT"

needs.test.result is one of success, failure, cancelled or skipped. The value is passed through env rather than interpolated into the script, which is the safe pattern for any expression value used in run.

To pass per-entry data to a later job, upload an artifact from each matrix entry with a unique name and download them in the final job. For a related walkthrough, see Pass Outputs Between GitHub Actions Jobs.

Verify the behavior

  1. Make the experimental entry fail, for example by adding - run: exit 1 guarded by if: matrix.experimental to its steps.
  2. Open the workflow run in the Actions tab. The failed experimental job shows its failing step in the log, while the run’s overall result is not failed.
  3. Make a non-experimental entry fail instead. With fail-fast: true, the remaining in-progress and queued jobs are cancelled and the run fails.
  4. If the run fails when only an experimental entry failed, check that experimental is defined for every combination and that continue-on-error is on the job, not only on a step.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.