Build Specification Reference for AWS CodeBuild

Build Spec File Name and Storage Location

If you include a build spec as part of the source code, the build spec file must be named buildspec.yml.

If you include a build spec as part of the source code, for an AWS CodeCommit or GitHub repository, it must be stored in the root (top level) of the repository that contains the source code. For an Amazon S3 bucket, the build spec must be stored in the root (top level) of the build input ZIP file that contains the source code.

Build Spec Syntax

Build specs must be expressed in YAML format.

The build spec has the following syntax:

version: 0.1

environment_variables:
  plaintext:
    key: "value"
    key: "value"
            
phases:
  install:
    commands:
      - command
      - command
  pre_build:
    commands:
      - command
      - command
  build:
    commands:
      - command
      - command
  post_build:
    commands:
      - command
      - command
artifacts:
  files:
    - location
    - location
  discard-paths: yes

The build spec contains the following:

version: Required mapping. Represents the build spec version. We recommend you use 0.1.
Note
Version 0.0 is still supported, but no longer documented. We recommend that you use version 0.1 whenever possible. For more information, see Build Spec Versions.
environment_variables: Optional sequence. Represents information for one or more custom environment variables.
- plaintext: Required if environment_variables is specified. Contains a mapping of key/value scalars, where each mapping represents a single custom environment variable.
Important
Any environment variables you set will replace existing environment variables. For example, if the Docker image already contains an environment variable named MY_VAR with a value of my_value, and you set an environment variable named MY_VAR with a value of other_value, then my_value will be replaced by other_value. Similarly, if the Docker image already contains an environment variable named PATH with a value of /usr/local/sbin:/usr/local/bin, and you set an environment variable named PATH with a value of $PATH:/usr/share/ant/bin, then /usr/local/sbin:/usr/local/bin will be replaced by the literal value $PATH:/usr/share/ant/bin.
Do not set any environment variable with a name that begins with CODEBUILD_. This prefix is reserved for internal use.
If an environment variable with the same name is defined in multiple places, the value is determined as follows:
- The value in the start build operation call takes highest precedence.
- The value in the build project definition takes next precedence.
- The value in the build spec declaration takes lowest precedence.
phases: Required sequence. Represents the commands AWS CodeBuild will run during each phase of the build. The allowed build phase names are:
- install: Optional sequence. Represents the commands, if any, that AWS CodeBuild will run during installation. We recommend you use the install phase only for installing packages in the build environment. For example, you might use this phase to install a code testing framework such as Mocha or RSpec.
  - commands: Required sequence if install is specified. Contains a sequence of scalars, where each scalar represents a single command that AWS CodeBuild will run during installation. AWS CodeBuild runs each command, one at a time, in the order listed, from beginning to end.
- pre_build: Optional sequence. Represents the commands, if any, that AWS CodeBuild will run before the build. For example, you might use this phase to log in to Amazon ECR, or you might install npm dependencies.
  - commands: Required sequence if pre_build is specified. Contains a sequence of scalars, where each scalar represents a single command that AWS CodeBuild will run before the build. AWS CodeBuild runs each command, one at a time, in the order listed, from beginning to end.
- build: Optional sequence. Represents the commands, if any, that AWS CodeBuild will run during the build. For example, you might use this phase to run Mocha, RSpec, or sbt.
  - commands: Required if build is specified. Contains a sequence of scalars, where each scalar represents a single command that AWS CodeBuild will run during the build. AWS CodeBuild runs each command, one at a time, in the order listed, from beginning to end.
- post_build: Optional sequence. Represents the commands, if any, that AWS CodeBuild will run after the build. For example, you might use Maven to package the build artifacts into a JAR or WAR file, or you might push a Docker image into Amazon ECR. Then you might send a build notification through Amazon SNS.
  - commands: Required if post_build is specified. Contains a sequence of scalars, where each scalar represents a single command that AWS CodeBuild will run after the build. AWS CodeBuild runs each command, one at a time, in the order listed, from beginning to end.
Important
Commands in some build phases might not be run if commands in earlier build phases fail. For example, if a command fails during the install phase, none of the commands in the pre_build, build, and post_build phases will be run for that build's lifecycle. For more information, see Build Phase Transitions.
AWS CodeBuild runs each command in a separate instance of the default shell in the build environment. This means that each command runs in isolation from all other commands. Therefore, by default, you cannot run a single command that relies on the state of any previous commands (for example, changing directories or setting environment variables). To get around this limitation, see the recommended approaches in Shells and Commands in Build Environments.
artifacts Required sequence. Represents information about where AWS CodeBuild can find the build output and how AWS CodeBuild will prepare it for uploading to the Amazon S3 output bucket.
- files: Required sequence. Represents the locations containing the build output artifacts in the build environment. Contains a sequence of scalars, with each scalar representing a separate location where AWS CodeBuild can find build output artifacts, relative to the original build location. Locations can include the following:
  - A single file (for example, my-file.jar).
  - A single file in a subdirectory (for example, my-subdirectory/my-file.jar or my-parent-subdirectory/my-subdirectory/my-file.jar).
  - '**/*' represents all files recursively.
  - my-subdirectory/* represents all files in a subdirectory named my-subdirectory.
  - my-subdirectory/**/* represents all files recursively starting from a subdirectory named my-subdirectory.
  When you specify build output artifact locations, AWS CodeBuild can locate the original build location in the build environment. You do not have to prepend your build artifact output locations with the path to the original build location or specify ./ or similar. If you want to know the path to this location, you can run a command such as echo $CODEBUILD_SRC_DIR during a build. The location for each build environment might be slightly different.
- discard-paths: Optional mapping. Represents whether paths to files in the build output artifact are preserved. yes if paths are preserved; otherwise, no or not specified (the default). For example, if a path to a file in the build output artifact would be com/mycompany/app/HelloWorld.java, then specifying yes would shorten this path to simply HelloWorld.java.

Important

Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important. If the number of spaces in your build spec declaration is invalid, builds might fail immediately. You can use a YAML validator to test whether your build spec declarations are valid YAML.

If you use the AWS CLI, the AWS SDKs, or the AWS CodeBuild HTTP API to declare a build spec when you create or update a build project, the build spec must be a single string expressed in YAML format, along with required whitespace and newline escape characters. There is an example in the next section.

If you use the AWS CodeBuild or AWS CodePipeline consoles instead of a buildspec.yml file, you can insert commands for the build phase only. Instead of using the preceding syntax, you list, in a single line, all of the commands you want to run during the build phase. For multiple commands, separate each command by && (for example, mvn test && mvn package).

You can use the AWS CodeBuild or AWS CodePipeline consoles instead of a buildspec.yml file to specify the locations of the build output artifacts in the build environment. Instead of using the preceding syntax, you list, in a single line, all of the locations. For multiple locations, separate each location with a comma (for example, appspec.yml, target/my-app.jar).

Build Spec Example

Here is an example of a buildspec.yml file.

version: 0.1

environment_variables:
  plaintext:
    JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"

phases:
  install:
    commands:
      - apt-get update -y
      - apt-get install -y maven
  pre_build:
    commands:
      - echo Nothing to do in the pre_build phase...
  build:
    commands:
      - echo Build started on `date`
      - mvn install
  post_build:
    commands:
      - echo Build completed on `date`
artifacts:
  files:
    - target/messageUtil-1.0.jar
  discard-paths: yes

Here is an example of the preceding build spec, expressed as a single string, for use with the AWS CLI, the AWS SDKs, or the AWS CodeBuild HTTP API.

"version: 0.1\n\nenvironment_variables:\n  plaintext:\n    JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"\n\nphases:\n  install:\n    commands:\n      - apt-get update -y\n      - apt-get install -y maven\n  pre_build:\n    commands:\n      - echo Nothing to do in the pre_build phase...\n  build:\n    commands:\n      - echo Build started on `date`\n      - mvn install\n  post_build:\n    commands:\n      - echo Build completed on `date`\nartifacts:\n  files:\n    - target/messageUtil-1.0.jar\n  discard-paths: yes"

Here is an example of the commands in the build phase, for use with the AWS CodeBuild or AWS CodePipeline consoles.

echo Build started on `date` && mvn install

In these examples:

A custom environment variable with the key of JAVA_HOME and the value of /usr/lib/jvm/java-8-openjdk-amd64 will be set.
You cannot change these build phase names. The only commands that will be run in this example are apt-get update -y and apt-get install -y maven (to install Apache Maven) and mvn install (to compile, test, and package the source code into a build output artifact and to perform other actions, such as install the build output artifact in its internal repository). The echo commands are included here to show how AWS CodeBuild runs commands and the order in which it runs them.
files represents the files to upload to the build output location. In this example, AWS CodeBuild will upload the single file messageUtil-1.0.jar. The messageUtil-1.0.jar file can be found in the relative directory named target in the build environment. Because discard-paths: yes is specified, messageUtil-1.0.jar will be uploaded directly (and not to an intermediate target directory). The file name messageUtil-1.0.jar and the relative directory name of target is based on the way Apache Maven creates and stores build output artifacts for this example only. In your own scenarios, these file names and directories will be different.

Build Spec Versions

The following table lists the build spec versions and the changes between versions.

Version Changes

0.1

Version	Changes
0.1	The `containers` and `tag` sequences have been removed. The `during_build` sequence has been renamed to `build`. The `type` mapping has been removed. All other sequences and mappings from version 0.0 are unchanged.
0.0	This is the initial build spec version. You can still use build specs that declare version 0.0. However, AWS CodeBuild will ignore the required `containers` and `tag` sequences in version 0.0 build specs. Version 0.0 will no longer be documented.

The containers and tag sequences have been removed.

The during_build sequence has been renamed to build.

The type mapping has been removed.

All other sequences and mappings from version 0.0 are unchanged.

0.0

This is the initial build spec version.

You can still use build specs that declare version 0.0. However, AWS CodeBuild will ignore the required containers and tag sequences in version 0.0 build specs.

Version 0.0 will no longer be documented.