Using a matrix for your jobs

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:

name: Matrix Configuration

on:
  push:
  workflow_dispatch:

jobs:
  deploy-on-ubuntu:
    runs-on: ubuntu-latest
    steps:
      - name: Echo Docker details
        run: docker info
      - name: Run image
        run: docker run hello-world

  deploy-on-windows:
    runs-on: windows-latest
    steps:
      - name: Echo Docker details
        run: docker info
      - name: Run image
        run: docker run hello-world

This configuration triggers on every push or manual dispatch and executes both jobs in parallel.

Both jobs complete successfully:

Inspecting the Windows job shows Docker client/server details:

And the hello-world output confirms success:

Run docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
6fff548006e037: Pulling fs layer
365b066fa8d: Pulling fs layer
6f16e5b22025: Pulling fs layer
...
Hello from Docker!
This message shows that your installation appears to be working correctly.

2. Why Use a Matrix Strategy?

Maintaining separate jobs for each OS, language version, or container image can quickly become repetitive and error-prone.

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:

name: Matrix Configuration

on:
  push:
  workflow_dispatch:

jobs:
  deploy:
    strategy:
      matrix:
        os: [ubuntu-latest, ubuntu-20.04, windows-latest]
        images: [hello-world, alpine]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Echo Docker details
        run: docker info

      - name: Run image on ${{ matrix.os }}
        run: docker run ${{ matrix.images }}

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:

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:

Run docker run alpine
Unable to find image 'alpine:latest' locally
latest: Pulling from library/alpine
docker: no matching manifest for windows/amd64 in the manifest list entries.
See 'docker run --help'.
Error: Process completed with exit code 1

In a future article, we’ll cover advanced filtering with exclude and conditional execution.

5. Further Reading

• GitHub Actions: Matrix strategy
• Docker Hub – Alpine Official Image
• GitHub Actions Workflow syntax for GitHub Actions

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