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 plugin attributes.

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 parellism 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}}"
  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):

Screenshot of an eight job matrix

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 10 dimensions, 10 elements in each dimension and a total of 10 adjustments.

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"