AWS CodeBuild Buildspec

External

Build Specification Reference for CodeBuild

Internal

• AWS CodeBuild Concepts

Example

version: 0.2

env:
  variables:
    DEPLOYMENT_STACK_CONFIG_FILE: "deployment-stack-config.json"
    MY_LOCAL_VAR: "some value"

phases:

  install:
    commands:
      - echo "'install' phase started on $(date)"
      #
      # check pre-conditions, like environment variable availability. The environment 'MY_VAR' tested
      # below is supposed to be set by the invoking layer (CodeBuild driven by CodePipeline):
      #
      - if [ -z "${MY_VAR}" ]; then echo "required MY_VAR variable not set" 1>&2; exit 1; fi

  build:
    commands:
    - echo "'build' phase started on $(date)"

  post_build:
    commands:
      - echo "'post_build' phase started on $(date)"
      - echo "{\"Parameters\":{\"MyConfigurationParameterA\":\"blue\", \"MyConfigurationParameterB\":\"red\"}}" > ./${DEPLOYMENT_STACK_CONFIG_FILE}

artifacts:
  files:
    - ${DEPLOYMENT_STACK_CONFIG_FILE}

Structure

env

variables

This section sets environment variables that will propagate to the container that performs the build:

env:
  variables:
    MY_VARIABLE: 'some value'

Note that if this build project is part of a CodePipeline pipeline, which is set up with a CloudFormation stack template, additional environment variables can be set at CodeBuild project/CloudFormation stack template level and passed to the build container, as shown here: CodePipeline-Driven CodeBuild Builds. The availability of such environment variable can be tested in the install phase of the build, as shown in the example, above.

Unfortunately, variables that refer other variables in the same block are not supported. The following will not work:

env:
  variables:
    A: "some value"
    B: "not ${A}"

artifacts

If this build is driven by CodePipeline, the artifacts declared here are placed, as S3 objects, into the CodePipeline Build action's Output Artifact, which is an S3 "folder". For more details about CodePipeline output artifacts, see:

CodePipeline Artifacts

Examples

Verifying that an Environment Variable is Set

...
phases:
  install:
    commands:
      - if [ -z "${AWS_REGION}" ]; then echo "AWS_REGION variable not set" 1>&2; exit 1; fi

Long Commands Declared on Multiple Lines in Buildspec

Bash commands can be pretty long, and when that is the case, they could be declared on multiple lines in the buildspec, for clarity, as follows:

...
phases:
  ...:
    commands:
      - |
        some-command an-argument \
          --option1=value1 \
          --option2=value2 \
          --option2=value3

The effect is similar to running the command as:

some-command an-argument --option1=value1 --option2=value2 --option2=value3

The "\" continuation character can be omitted at the end of the lines if the command can be naturally declared on multiple lines, as such:

...
phases:
  ...:
    commands:
      - |
        if [ -z "${AWS_REGION}" ]; then 
          echo "AWS_REGION variable not set" 1>&2
        else
          echo "AWS_REGION=${AWS_REGION}"
        fi

Manually Starting a Docker Server

If the build image is custom, and it is a privileged image, meaning that it needs to interact with the. Docker server, CodeBuild will not start the Docker server, and we will need to start it manually, as follows:

phases:
  install:
    commands:
      #
      # Manually start a Docker server, as it is not automatically started for custom images. Not necessary for
      # AWS-managed images, the Docker server will be started by default in those cases.
      #
      - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2&
      - timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

Organizatorium

• An environment variable exported with the following command in an early phase (install) is visible to subsequent phases:

- export PIPELINE_RUN_ID=1

• I have encountered situations when scripts (gradlew) that come part as the source code tree and are set to be executable in GitHub lose their execution flag needed when they are to be run in the build image. The solution is to:

- chmod a+x ./gradlew
- ./gradlew clean build