Build matrix

Build matrices help you simplify complex build configurations by expanding a step template and array of matrix elements into multiple jobs.

The following command step attributes can contain matrix values for interpolation:

You can't use matrix values in other attributes, including step keys and concurrency groups.

For example, instead of writing three separate jobs for builds on macOS, Linux, and Windows, like the following build configuration (which does not use a build matrix):

pipeline.yml

steps:
  - label: "macOS build"
    command: "GOOS=darwin go build"
  - label: "Linux build"
    command: "GOOS=linux go build"
  - label: "Windows build"
    command: "GOOS=windows go build"

Use a build matrix to expand a single step template into three steps by interpolating the matrix values into the following build configuration:

pipeline.yml

steps:
  - label: "{{matrix}} build"
    command: "GOOS={{matrix}} go build"
    env:
      os: "{{matrix}}"
    matrix:
      - "darwin"
      - "Linux"
      - "Windows"

All jobs created by a build matrix are marked with the Matrix badge in the Buildkite interface.

Matrix and Parallel steps

Matrix builds are not compatible with explicit parallelism in steps. You can use a matrix and parallelism in the same build, as long as they are on separate steps.

For more complex builds, add multiple dimensions to matrix.setup instead of the matrix array:

pipeline.yml

steps:
- label: "💥 Matrix Build"
  command: "echo {{matrix.os}} {{matrix.arch}} {{matrix.test}}"
  agents:
    queue: "builder-{{matrix.arch}}"
  matrix:
    setup:
      arch:
        - "amd64"
        - "arm64"
      os:
        - "windows"
        - "linux"
      test:
        - "A"
        - "B"

Each dimension you add is multiplied by the other dimensions, so two architectures (matrix.setup.arch), two operating systems (matrix.setup.os), and two tests (matrix.setup.test) create an eight job build (2 * 2 * 2 = 8):

If you're using matrix.setup, you can also use the adjustments key to change specific entries in the build matrix, or add new combinations. You can set the skip attribute to effectively remove them from the matrix, or soft_fail attributes to allow them to fail without breaking the build.

pipeline.yml

steps:
- label: "💥 Matrix build with adjustments"
  command: "echo {{matrix.os}} {{matrix.arch}} {{matrix.test}}"
  matrix:
    setup:
      arch:
        - "amd64"
        - "arm64"
      os:
        - "windows"
        - "linux"
      test:
        - "A"
        - "B"
    adjustments:
      - with:
          os: "windows"
          arch: "arm64"
          test: "B"
        soft_fail: true
      - with:
          os: "linux"
          arch: "arm64"
          test: "B"
        skip: true

Adding combinations to the build matrix

To add an extra combination that isn't present in the matrix.setup, use the adjustments key and make sure to define all of the elements in the matrix. For example, to add a build for Plan 9 (on arm64, and test suite B) to the previous example, use:

pipeline.yml

    adjustments:
      - with:
          os: "Plan 9"
          arch: "arm64"
          test: "B"

This results in nine jobs, (2 * 2 * 2 + 1 = 9).

Removing combinations from the build matrix

To remove a combination from the matrix, add it to the adjustments key and set skip: true:

pipeline.yml

    adjustments:
      - with:
          os: "linux"
          arch: "arm64"
          test: "B"
        skip: true

Matrix limits

Each build matrix has a limit of 6 dimensions, 20 elements in each dimension, and a total of 12 adjustments. The matrix configuration on a command has a limit of 50 jobs created.

Grouping matrix elements

When you're creating many jobs with a matrix, you might want to group them together, for a tidier view.

Screenshot of an eight job matrix inside a group step

To do that, indent the matrix steps inside a group step:

steps:
  - group: "📦 Build"
    steps:
      - label: "💥 Matrix build with adjustments"
        command: "echo {{matrix.os}} {{matrix.arch}} {{matrix.test}}"
        matrix:
          setup:
            arch:
              - "amd64"
              - "arm64"
            os:
              - "windows"
              - "linux"
            test:
              - "A"
              - "B"