How to Build a Matrix of Docker Image Variants in CI

A matrix fans one build definition out across variants, building each flavor in its own parallel job.

Put the variant list in strategy.matrix, then reference matrix.<key> in the build args and tags. Each combination builds independently, so a broken variant does not block the others when fail-fast is off.

Steps

• List the variants under strategy.matrix (e.g. base versions).
• Pass build-args and tags derived from the matrix value.
• Set fail-fast: false so every variant reports its own result.

Workflow

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        variant: ['20', '22']
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/build-push-action@v6
        with:
          push: true
          build-args: |
            NODE_VERSION=${{ matrix.variant }}
          tags: ghcr.io/${{ github.repository }}:node${{ matrix.variant }}

Gotchas

• Each matrix leg pushes a distinct tag; make sure the tags differ or later legs overwrite earlier ones.
• Latchkey runs matrix builds on cheaper managed runners and auto-retries transient failures.

Related guides