Skip to main content
GitHub Actions matrix strategy lets you run the same job across multiple environments—OS versions, language runtimes, or Docker images—without duplicating workflow steps. This approach maximizes parallelism, simplifies maintenance, and accelerates your CI/CD pipeline.

​
Table of Contents

  1. A Straightforward Workflow
  2. Why Use a Matrix Strategy?
  3. Converting to a Matrix Workflow
  4. Handling Failures in a Matrix
  5. Further Reading

​
1. A Straightforward Workflow

Here’s a basic GitHub Actions workflow that runs two independent jobs—one on Ubuntu, one on Windows—to echo Docker info and launch the hello-world container:
This configuration triggers on every push or manual dispatch and executes both jobs in parallel.
The image shows a GitHub Actions interface displaying a list of workflow runs, including their status, branch, and execution time. The highlighted workflow is "matrix example - 1," which is currently in progress.
Both jobs complete successfully:
The image shows a GitHub Actions workflow summary with successful deployment jobs for Ubuntu and Windows. The workflow is named "matrix example - 1" and has a total duration of 1 minute and 10 seconds.
Inspecting the Windows job shows Docker client/server details:
The image shows a GitHub Actions workflow interface with a job named "deploy-on-windows" that has succeeded. It includes details about Docker, such as client version and server information.
And the hello-world output confirms success:

​
2. Why Use a Matrix Strategy?

Maintaining separate jobs for each OS, language version, or container image can quickly become repetitive and error-prone.
Matrix strategy automatically runs all defined combinations in parallel, speeding up CI/CD feedback.
For full details on matrix strategies, see the GitHub Actions documentation.

​
3. Converting to a Matrix Workflow

Let’s test two Docker images—hello-world and alpine—across three platforms: ubuntu-latest, ubuntu-20.04, and windows-latest. We’ll leverage the matrix variables in both runs-on and our Docker commands:
The image shows a GitHub Actions interface with a workflow run summary for a matrix job, displaying details of a deployment on Ubuntu.
GitHub Actions will now run 3 OS × 2 images = 6 jobs in parallel, improving CI throughput. After committing these changes, your matrix workflow appears like this:
The image shows a GitHub Actions workflow interface with a matrix configuration, displaying the status of various deployment jobs for different environments.

​
4. Handling Failures in a Matrix

By default, any failing combination halts the workflow and marks it as failed. For example, alpine isn’t compatible with Windows, so that job errors out:
The image shows a GitHub Actions page with a matrix configuration where some deployment jobs have succeeded and one has failed, resulting in an overall failure status.
A single matrix failure by default stops all running jobs. Use strategy.fail-fast: false or exclude incompatible combinations with matrix.exclude.
In a future article, we’ll cover advanced filtering with exclude and conditional execution.

​
5. Further Reading

That’s it—happy automating with GitHub Actions matrix strategies!

Watch Video