Batch builds in AWS CodeBuild - AWS CodeBuild
Security roleBatch build typesMore information

Batch builds in AWS CodeBuild

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:

  • Giving the build role StartBuild, StopBuild, and RetryBuild permissions would allow a single build to start more builds via the buildspec.

  • CodeBuild batch builds provide restrictions that restrict the number of builds and compute types that can be used for the builds in the batch. If the build role has these permissions, it is possible the builds themselves could bypass these restrictions.

Batch build types

CodeBuild supports the following batch build types:

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:
        compute-type: BUILD_GENERAL1_SMALL
      debug-session: true
    - identifier: build2
      env:
        compute-type: BUILD_GENERAL1_MEDIUM
      depend-on:
        - build1
      debug-session: false
    - identifier: build3
      env:
        compute-type: BUILD_GENERAL1_LARGE
      depend-on:
        - build2

In this example:

  • build1 runs first because it has no dependencies.

  • build2 has a dependency on build1, so build2 runs after build1 completes.

  • build3 has a dependency on build2, so build3 runs after build2 completes.

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 linux_small and windows_medium builds will be run in parallel. 

batch:
  fast-fail: false
  build-list:
    - identifier: linux_small
      env:
        compute-type: BUILD_GENERAL1_SMALL
      ignore-failure: true
      debug-session: true
    - identifier: windows_medium
      env:
        type: WINDOWS_SERVER_2019_CONTAINER
        image: aws/codebuild/windows-base:2019-1.0
        compute-type: BUILD_GENERAL1_MEDIUM

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
      env:
        type: LINUX_CONTAINER
        image: aws/codebuild/amazonlinux2-x86_64-standard:3.0
        privileged-mode: true
    dynamic:
      buildspec: 
        - matrix1.yml
        - matrix2.yml
      env:
        variables:
          MY_VAR:
            - VALUE1
            - VALUE2
            - VALUE3

In this example, CodeBuild creates six builds:

  • matrix1.yml with $MY_VAR=VALUE1

  • matrix1.yml with $MY_VAR=VALUE2

  • matrix1.yml with $MY_VAR=VALUE3

  • matrix2.yml with $MY_VAR=VALUE1

  • matrix2.yml with $MY_VAR=VALUE2

  • matrix2.yml with $MY_VAR=VALUE3

Each build will have the following settings:

  • ignore-failure set to false

  • env/type set to LINUX_CONTAINER

  • env/image set to aws/codebuild/amazonlinux2-x86_64-standard:3.0

  • env/privileged-mode set to true

These builds run in parallel.

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

More information

For more information, see the following topics: