You can use AWS CodeBuild to run concurrent and coordinated builds of a project with batch builds.

Security role

Batch builds introduce a new security role in the batch configuration. This new role is required as CodeBuild must be able to call the StartBuild, StopBuild, and RetryBuild actions on your behalf to run builds as part of a batch. Customers should use a new role, and not the same role they use in their build, for two reasons:

Batch build types

CodeBuild supports the following batch build types:

Build graph

A build graph defines a set of tasks that have dependencies on other tasks in the batch.

The following example defines a build graph that creates a dependency chain.

batch:
  fast-fail: false
  build-graph:
    - identifier: build1
      env:
        variables:
          BUILD_ID: build1
      ignore-failure: false
    - identifier: build2
      buildspec: build2.yml
      env:
        variables:
          BUILD_ID: build2
      depend-on:
        - build1
    - identifier: build3
      env:
        variables:
          BUILD_ID: build3
      depend-on:
        - build2
    - identifier: build4
      env:
        compute-type: ARM_LAMBDA_1GB
    - identifier: build5
      env:
        fleet: fleet_name

In this example:

For more information about the build graph buildspec syntax, see batch/build-graph.

Build list

A build list defines a number of tasks that run in parallel.

The following example defines a build list. The build1 and build2 builds will run in parallel.

batch:
  fast-fail: false
  build-list:
    - identifier: build1
      env:
        variables:
          BUILD_ID: build1
      ignore-failure: false
    - identifier: build2
      buildspec: build2.yml
      env:
        variables:
          BUILD_ID: build2
      ignore-failure: true
    - identifier: build3
      env:
        compute-type: ARM_LAMBDA_1GB
    - identifier: build4
      env:
        fleet: fleet_name
    - identifier: build5
      env:
        compute-type: GENERAL_LINUX_XLAGRE

For more information about the build list buildspec syntax, see batch/build-list.

Build matrix

A build matrix defines tasks with different configurations that run in parallel. CodeBuild creates a separate build for each possible configuration combination.

The following example shows a build matrix with two buildspec files and three values for an environment variable.

batch:
  build-matrix:
    static:
      ignore-failure: false
    dynamic:
      buildspec: 
        - matrix1.yml
        - matrix2.yml
      env:
        variables:
          MY_VAR:
            - VALUE1
            - VALUE2
            - VALUE3

In this example, CodeBuild creates six builds:

Each build will have the following settings:

These builds run in parallel.

For more information about the build matrix buildspec syntax, see batch/build-matrix.

Build fanout

A build fanout defines a task that will be split into multiple builds in the batch. This can be used for running tests in parallel. CodeBuild creates a separate build for each shard of test cases based on the value set in parallelism field.

The following example defines a build fanout that creates five builds that run in parallel.

version: 0.2

batch:
   fast-fail: false 
   build-fanout:
     parallelism: 5
     ignore-failure: false

phases:
  install:
    commands:
      - npm install
   build:
    commands:
      - mkdir -p test-results
      - cd test-results
      - |
        codebuild-tests-run \
         --test-command 'npx jest --runInBand --coverage' \
         --files-search "codebuild-glob-search '**/test/**/*.test.js'" \
         --sharding-strategy 'equal-distribution'  

In this example, assuming that there are 100 tests that needs to be run, CodeBuild creates five builds that each runs 20 tests in parallel.

For more information about the build graph buildspec syntax, see batch/build-fanout.

Batch report mode

If the source provider for your project is Bitbucket, GitHub, or GitHub Enterprise, and your project is configured to report build statuses to the source provider, you can select how you want your batch build statuses sent to the source provider. You can select to have the statuses sent as a single aggregate status report for the batch, or have the status of each build in the batch reported individually.

For more information, see the following topics:

More information

For more information, see the following topics: