Build specification reference for CodeBuild

Optional sequence. Specifies the supported shell for Linux or Windows operating systems.

For Linux operating systems, supported shell tags are:

For Windows operating systems, supported shell tags are:

Required if env is specified, and you want to define custom environment variables in plain text. Contains a mapping of key/value scalars, where each mapping represents a single custom environment variable in plain text. key is the name of the custom environment variable, and value is that variable's value.

Required if env is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store. Contains a mapping of key/value scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store. key is the name you use later in your build commands to refer to this custom environment variable, and value is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store. To store sensitive values, see Systems Manager Parameter Store and Walkthrough: Create and test a String parameter (console) in the Amazon EC2 Systems Manager User Guide.

Required if you want to retrieve custom environment variables stored in AWS Secrets Manager. Specify a Secrets Manager reference-key using the following pattern:

<key>: <secret-id>:<json-key>:<version-stage>:<version-id>

In the following example, TestSecret is the name of the key-value pair stored in Secrets Manager. The key for TestSecret is MY_SECRET_VAR. You access the variable during the build using the LOCAL_SECRET_VAR name.

env:
  secrets-manager:
    LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR"

For more information, see What is AWS Secrets Manager in the AWS Secrets Manager User Guide.

Optional mapping. Used to list environment variables you want to export. Specify the name of each variable you want to export on a separate line under exported-variables. The variable you want to export must be available in your container during the build. The variable you export can be an environment variable.

Exported environment variables are used in conjunction with AWS CodePipeline to export environment variables from the current build stage to subsequent stages in the pipeline. For more information, see Working with variables in the AWS CodePipeline User Guide.

During a build, the value of a variable is available starting with the install phase. It can be updated between the start of the install phase and the end of the post_build phase. After the post_build phase ends, the value of exported variables cannot change.

Optional mapping. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials. yes if it is used. Otherwise, no or not specified. For more information, see gitcredentials on the Git website.

Optional mapping. Set to yes if you want your build in an explicit proxy server to upload artifacts. The default is no.

Optional mapping. Set to yes for your build in a explicit proxy server to create CloudWatch logs. The default is no.

Optional sequence. Use in a build phase to specify a Linux user that runs its commands. If run-as is also specified globally for all commands at the top of the buildspec file, then the phase-level user takes precedence. For example, if globally run-as specifies User-1, and for the install phase only a run-as statement specifies User-2, then all commands in then buildspec file are run as User-1 except commands in the install phase, which are run as User-2.

Optional sequence. Specifies the action to take if a failure occurs during the phase. This can be one of the following values:

If this property is not specified, the failure process follows the transition phases as shown in Build phase transitions.

Optional block. Commands specified in a finally block are run after commands in the commands block. The commands in a finally block are run even if a command in the commands block fails. For example, if the commands block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the finally block. The phase is successful when all commands in the commands and the finally blocks run successfully. If any command in a phase fails, the phase fails.

Optional sequence. Represents the commands, if any, that CodeBuild runs during installation. We recommend that 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.

Optional sequence. Represents the commands, if any, that CodeBuild runs before the build. For example, you might use this phase to sign in to Amazon ECR, or you might install npm dependencies.

Optional sequence. Represents the commands, if any, that CodeBuild runs during the build. For example, you might use this phase to run Mocha, RSpec, or sbt.

Optional sequence. Represents the commands, if any, that CodeBuild runs 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.

Optional sequence. Specifies the report group that the reports are sent to. A project can have a maximum of five report groups. Specify the ARN of an existing report group, or the name of a new report group. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format <project-name>-<report-group-name>. The report group name can also be set using an environment variable in the buildspec such as $REPORT_GROUP_NAME. For more information, see Report group naming.

Required sequence. Represents the locations that contain the raw data of test results generated by the report. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the base-directory. Locations can include the following:

Optional mapping. Represents the report file format. If not specified, JUNITXML is used. This value is not case sensitive. Possible values are:

Optional mapping. Represents one or more top-level directories, relative to the original build location, that CodeBuild uses to determine where to find the raw test files.

Optional. Specifies if the report file directories are flattened in the output. If this is not specified, or contains no, report files are output with their directory structure intact. If this contains yes, all of the test files are placed in the same output directory. For example, if a path to a test result is com/myapp/mytests/TestResult.xml, specifying yes will place this file in /TestResult.xml.

Required sequence. Represents the locations that contain the build output artifacts in the build environment. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find build output artifacts, relative to the original build location or, if set, the base directory. Locations can include the following:

When you specify build output artifact locations, 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.

Optional name. Specifies a name for your build artifact. This name is used when one of the following is true.

You can specify a name in the buildspec file that is calculated at build time. The name specified in a buildspec file uses the Shell command language. For example, you can append a date and time to your artifact name so that it is always unique. Unique artifact names prevent artifacts from being overwritten. For more information, see Shell command language.

You can add path information to the name so that the named artifacts are placed in directories based on the path in the name. In this example, build artifacts are placed in the output under builds/<build number>/my-artifacts.

version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts

Optional. Specifies if the build artifact directories are flattened in the output. If this is not specified, or contains no, build artifacts are output with their directory structure intact. If this contains yes, all of the build artifacts are placed in the same output directory. For example, if a path to a file in the build output artifact is com/mycompany/app/HelloWorld.java, specifying yes will place this file in /HelloWorld.java.

Optional mapping. Represents one or more top-level directories, relative to the original build location, that CodeBuild uses to determine which files and subdirectories to include in the build output artifact. Valid values include:

Matching top-level directories are not included in the build output artifact, only their files and subdirectories.

You can use files and discard-paths to further restrict which files and subdirectories are included. For example, for the following directory structure:

.
├── my-build-1
│   └── my-file-1.txt
└── my-build-2
    ├── my-file-2.txt
    └── my-subdirectory
        └── my-file-3.txt

And for the following artifacts sequence:

artifacts:
  files:
    - '*/my-file-3.txt'
  base-directory: my-build-2

The following subdirectory and file would be included in the build output artifact:

.
└── my-subdirectory
    └── my-file-3.txt

While for the following artifacts sequence:

artifacts:
  files:
    - '**/*'
  base-directory: 'my-build*'
  discard-paths: yes

The following files would be included in the build output artifact:

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt

Optional mapping. Represents one or more paths, relative to base-directory, that CodeBuild will exclude from the build artifacts. The asterisk (*) character matches zero or more characters of a name component without crossing folder boundaries. A double asterisk (**) matches zero or more characters of a name component across all directories.

Examples of exclude-paths include the following:

Optional. If the output type is ZIP, specifies if internal symbolic links are preserved in the ZIP file. If this contains yes, all internal symbolic links in the source will be preserved in the artifacts ZIP file.

Optional. Specifies a prefix used when the artifacts are output to an Amazon S3 bucket and the namespace type is BUILD_ID. When used, the output path in the bucket is <s3-prefix>/<build-id>/<name>.zip.

Optional sequence. Represents one or more artifact definitions as a mapping between an artifact identifier and an artifact definition. Each artifact identifiers in this block must match an artifact defined in the secondaryArtifacts attribute of your project. Each separate definition has the same syntax as the artifacts block above.

For example, if your project has the following structure:

{
  "name": "sample-project",
  "secondaryArtifacts": [
    {
      "type": "S3",
      "location": "<output-bucket1>",
      "artifactIdentifier": "artifact1",
      "name": "secondary-artifact-name-1"
    },
    {
      "type": "S3",
      "location": "<output-bucket2>",
      "artifactIdentifier": "artifact2",
      "name": "secondary-artifact-name-2"
    }
  ]
}

Then your buildspec looks like the following:

version: 0.2

phases:
build:
  commands:
    - echo Building...
artifacts:
  files:
    - '**/*'
  secondary-artifacts:
    artifact1:
      files:
        - directory/file1
      name: secondary-artifact-name-1
    artifact2:
      files:
        - directory/file2
      name: secondary-artifact-name-2

Required sequence. Represents the locations of the cache. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find build output artifacts, relative to the original build location or, if set, the base directory. Locations can include the following: