Build specification reference for CodeBuild (original) (raw)

This topic provides important reference information about build specification (buildspec) files. A buildspec is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project. For information about how a build spec works, see How CodeBuild works.

Topics

Buildspec file name and storage location
Buildspec syntax
Buildspec example
Buildspec versions
Batch build buildspec reference

Buildspec file name and storage location

If you include a buildspec as part of the source code, by default, the buildspec file must be named buildspec.yml and placed in the root of your source directory.

You can override the default buildspec file name and location. For example, you can:

Use a different buildspec file for different builds in the same repository, such as buildspec_debug.yml andbuildspec_release.yml.
Store a buildspec file somewhere other than the root of your source directory, such as config/buildspec.yml or in an S3 bucket. The S3 bucket must be in the same AWS Region as your build project. Specify the buildspec file using its ARN (for example, arn:aws:s3:::`<my-codebuild-sample2>`/buildspec.yml).

You can specify only one buildspec for a build project, regardless of the buildspec file's name.

To override the default buildspec file name, location, or both, do one of the following:

Run the AWS CLI create-project orupdate-project command, setting thebuildspec value to the path to the alternate buildspec file relative to the value of the built-in environment variableCODEBUILD_SRC_DIR. You can also do the equivalent with thecreate project operation in the AWS SDKs. For more information, see Create a build project or Change build project settings.
Run the AWS CLI start-build command, setting thebuildspecOverride value to the path to the alternate buildspec file relative to the value of the built-in environment variableCODEBUILD_SRC_DIR. You can also do the equivalent with thestart build operation in the AWS SDKs. For more information, see Run builds manually.
In an AWS CloudFormation template, set the BuildSpec property ofSource in a resource of typeAWS::CodeBuild::Project to the path to the alternate buildspec file relative to the value of the built-in environment variableCODEBUILD_SRC_DIR. For more information, see the BuildSpec property in AWS CodeBuild project source in the AWS CloudFormation User Guide.

Buildspec syntax

Buildspec files must be expressed in YAML format.

If a command contains a character, or a string of characters, that is not supported by YAML, you must enclose the command in quotation marks (""). The following command is enclosed in quotation marks because a colon (:) followed by a space is not allowed in YAML. The quotation mark in the command is escaped (\").

"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"

The buildspec has the following syntax:

version: 0.2

run-as: Linux-user-name

env:
  shell: shell-tag
  variables:
    key: "value"
    key: "value"
  parameter-store:
    key: "value"
    key: "value"
  exported-variables:
    - variable
    - variable
  secrets-manager:
    key: secret-id:json-key:version-stage:version-id
  git-credential-helper: no | yes

proxy:
  upload-artifacts: no | yes
  logs: no | yes

batch:
  fast-fail: false | true
  # build-list:
  # build-matrix:
  # build-graph:
  # build-fanout:
        
phases:
  install:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    commands:
      - command
      - command
    finally:
      - command
      - command
    
reports:
  report-group-name-or-arn:
    files:
      - location
      - location
    base-directory: location
    discard-paths: no | yes
    file-format: report-format
artifacts:
  files:
    - location
    - location
  name: artifact-name
  discard-paths: no | yes
  base-directory: location
  exclude-paths: excluded paths
  enable-symlinks: no | yes
  s3-prefix: prefix
  secondary-artifacts:
    artifactIdentifier:
      files:
        - location
        - location
      name: secondary-artifact-name
      discard-paths: no | yes
      base-directory: location
    artifactIdentifier:
      files:
        - location
        - location
      discard-paths: no | yes
      base-directory: location
cache:
  key: key
  fallback-keys:
    - fallback-key
    - fallback-key
  action: restore | save
  paths:
    - path
    - path

The buildspec contains the following:

version

Required mapping. Represents the buildspec version. We recommend that you use0.2.

Note

Although version 0.1 is still supported, we recommend that you use version 0.2 whenever possible. For more information, see Buildspec versions.

run-as

Optional sequence. Available to Linux users only. Specifies a Linux user that runs commands in this buildspec file. run-as grants the specified user read and run permissions. When you specify run-as at the top of the buildspec file, it applies globally to all commands. If you don't want to specify a user for all buildspec file commands, you can specify one for commands in a phase by using run-as in one of the phases blocks. Ifrun-as is not specified, then all commands run as the root user.

env

Optional sequence. Represents information for one or more custom environment variables.

env/shell

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

For Linux operating systems, supported shell tags are:

bash
/bin/sh

For Windows operating systems, supported shell tags are:

powershell.exe
cmd.exe

env/variables

Required if env is specified, and you want to define custom environment variables in plain text. Contains a mapping ofkey/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.

Important

We strongly discourage the storing of sensitive values in environment variables. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI. For sensitive values, we recommend that you use parameter-store orsecrets-manager mapping instead, as described later in this section.

Any environment variables you set replace existing environment variables. For example, if the Docker image already contains an environment variable named MY_VAR with a value ofmy_value, and you set an environment variable namedMY_VAR with a value of other_value, then my_value is 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 is replaced by the literal value $PATH:/usr/share/ant/bin.

Do not set any environment variable with a name that starts withCODEBUILD_. 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. You can add or override environment variables when you create a build. For more information, see Run AWS CodeBuild builds manually.
The value in the build project definition takes next precedence. You can add environment variables at the project level when you create or edit a project. For more information, see Create a build project in AWS CodeBuild and Change build project settings in AWS CodeBuild.
The value in the buildspec declaration takes lowest precedence.

env/parameter-store

Required if env is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store. Contains a mapping ofkey/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, andvalue 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.

Important

To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add thessm:GetParameters action to your CodeBuild service role. For more information, see Allow CodeBuild to interact with other AWS services.

Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store replace existing environment variables. For example, if the Docker image already contains an environment variable namedMY_VAR with a value of my_value, and you retrieve an environment variable named MY_VAR with a value of other_value, then my_value is 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 retrieve an environment variable named PATH with a value of $PATH:/usr/share/ant/bin, then/usr/local/sbin:/usr/local/bin is replaced by the literal value $PATH:/usr/share/ant/bin.

Do not store any environment variable with a name that starts withCODEBUILD_. 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. You can add or override environment variables when you create a build. For more information, see Run AWS CodeBuild builds manually.
The value in the build project definition takes next precedence. You can add environment variables at the project level when you create or edit a project. For more information, see Create a build project in AWS CodeBuild and Change build project settings in AWS CodeBuild.
The value in the buildspec declaration takes lowest precedence.

env/secrets-manager

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>`

<key>

(Required) The local environment variable name. Use this name to access the variable during the build.

<secret-id>

(Required) The name or Amazon Resource Name (ARN) that serves as a unique identifier for the secret. To access a secret in your AWS account, simply specify the secret name. To access a secret in a different AWS account, specify the secret ARN.

<json-key>

(Optional) Specifies the key name of the Secrets Manager key-value pair whose value you want to retrieve. If you do not specify ajson-key, CodeBuild retrieves the entire secret text.

<version-stage>

(Optional) Specifies the secret version that you want to retrieve by the staging label attached to the version. Staging labels are used to keep track of different versions during the rotation process. If you use version-stage, don't specifyversion-id. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of AWSCURRENT.

<version-id>

(Optional) Specifies the unique identifier of the version of the secret that you want to use. If you specify version-id, don't specify version-stage. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of AWSCURRENT.

In the following example, TestSecret is the name of the key-value pair stored in Secrets Manager. The key for TestSecret isMY_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.

env/exported-variables

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 theinstall phase. It can be updated between the start of theinstall phase and the end of the post_build phase. After the post_build phase ends, the value of exported variables cannot change.

Note

The following cannot be exported:

Amazon EC2 Systems Manager Parameter Store secrets specified in the build project.
Secrets Manager secrets specified in the build project
Environment variables that start with AWS_.

env/git-credential-helper

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, seegitcredentials on the Git website.

Note

git-credential-helper is not supported for builds that are triggered by a webhook for a public Git repository.

proxy

Optional sequence. Used to represent settings if you run your build in an explicit proxy server. For more information, see Run CodeBuild in an explicit proxy server.

proxy/upload-artifacts

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

proxy/logs

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

phases

Required sequence. Represents the commands CodeBuild runs during each phase of the build.

Note

In buildspec version 0.1, 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, we recommend that you use version 0.2, which solves this issue. If you must use buildspec version 0.1, we recommend the approaches in Shells and commands in build environments.

phases/*/run-as

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 arun-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.

phases/*/on-failure

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

ABORT - Abort the build.
CONTINUE - Continue to the next phase.
RETRY - Retry the build up to 3 times with an error message that matches the regular expression .*.
RETRY-`count` - Retry the build for a specified number of times, as represented by count with an error message that matches the regular expression .*. Note that count must be between 0 and 100. For example, valid values include RETRY-4 and RETRY-8.
RETRY-`regex` - Retry the build up to 3 times, and use regex to include a regular expression to match a specifed error message. For example, valid values include Retry-.*Error: Unable to connect to database.* and RETRY-invalid+.
RETRY-`count`-`regex` - Retry the build for a specified number of times, as represented by count. Note that count must be between 0 and 100. You can also use regex to include a regular expression to match the error message. For example, valid values include Retry-3-.*connection timed out.* and RETRY-8-invalid+.

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

phases/*/finally

Optional block. Commands specified in afinally block are run after commands in thecommands 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 thefinally block. The phase is successful when all commands in thecommands and the finally blocks run successfully. If any command in a phase fails, the phase fails.

The allowed build phase names are:

phases/install

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.

phases/install/runtime-versions

Optional sequence. A runtime version is supported with the Ubuntu standard image 5.0 or later and the Amazon Linux 2 standard image 4.0 or later. If specified, at least one runtime must be included in this section. Specify a runtime using a specific version, a major version followed by .x to specify that CodeBuild uses that major version with its latest minor version, orlatest to use the most recent major and minor version (for example, ruby: 3.2, nodejs: 18.x, orjava: latest). You can specify the runtime using a number or an environment variable. For example, if you use the Amazon Linux 2 standard image 4.0, then the following specifies that version 17 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed. For more information, see Docker images provided by CodeBuild.

phases:
  install:
    runtime-versions:
      java: corretto8
      python: 3.x
      ruby: "$MY_RUBY_VAR"

You can specify one or more runtimes in the runtime-versions section of your buildspec file. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use. If you specify one or more runtimes, CodeBuild uses only those runtimes. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you.

If two specified runtimes conflict, the build fails. For example, android: 29 and java: openjdk11 conflict, so if both are specified, the build fails.

For more information about the available runtimes, see Available runtimes.

Note

If you specify a runtime-versions section and use an image other than Ubuntu Standard Image 2.0 or later, or the Amazon Linux 2 (AL2) standard image 1.0 or later, the build issues the warning, "Skipping install of runtimes. Runtime version selection is not supported by this build image."

phases/install/commands

Optional sequence. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during installation. CodeBuild runs each command, one at a time, in the order listed, from beginning to end.

phases/pre_build

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.

phases/pre_build/commands

Required sequence if pre_build is specified. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs before the build. CodeBuild runs each command, one at a time, in the order listed, from beginning to end.

phases/build

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.

phases/build/commands

Required if build is specified. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during the build. CodeBuild runs each command, one at a time, in the order listed, from beginning to end.

phases/post_build

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.

phases/post_build/commands

Required if post_build is specified. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs after the build. CodeBuild runs each command, one at a time, in the order listed, from beginning to end.

reports

report-group-name-or-arn

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.

reports//files

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, thebase-directory. Locations can include the following:

A single file (for example,my-test-report-file.json).
A single file in a subdirectory (for example,`my-subdirectory`/my-test-report-file.json or`my-parent-subdirectory`/`my-subdirectory`/my-test-report-file.json).
'**/*' represents all files recursively.
`my-subdirectory`/* represents all files in a subdirectory namedmy-subdirectory.
`my-subdirectory`/**/* represents all files recursively starting from a subdirectory named my-subdirectory.

reports//file-format

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

Test reports

CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Code coverage reports

CLOVERXML

Clover XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

reports//base-directory

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.

reports//discard-paths

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.

artifacts

Optional sequence. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the S3 output bucket. This sequence is not required if, for example, you are building and pushing a Docker image to Amazon ECR, or you are running unit tests on your source code, but not building it.

Note

Amazon S3 metadata has a CodeBuild header named x-amz-meta-codebuild-buildarn which contains the buildArn of the CodeBuild build that publishes artifacts to Amazon S3. The buildArn is added to allow source tracking for notifications and to reference which build the artifact is generated from.

artifacts/files

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:

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 namedmy-subdirectory.
`my-subdirectory`/**/* represents all files recursively starting from a subdirectory named my-subdirectory.

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 asecho $CODEBUILD_SRC_DIR during a build. The location for each build environment might be slightly different.

artifacts/name

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

You use the CodeBuild API to create your builds and theoverrideArtifactName flag is set on theProjectArtifacts object when a project is updated, a project is created, or a build is started.
You use the CodeBuild console to create your builds, a name is specified in the buildspec file, and you select Enable semantic versioning when you create or update a project. For more information, see Create a build project (console).

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.

This is an example of an artifact name appended with the date the artifact is created.

version: 0.2  
phases:  
  build:  
    commands:  
      - rspec HelloWorld_spec.rb  
artifacts:  
  files:  
    - '**/*'  
  name: myname-$(date +%Y-%m-%d)

This is an example of an artifact name that uses a CodeBuild environment variable. For more information, see Environment variables in build environments.

version: 0.2  
phases:  
  build:  
    commands:  
      - rspec HelloWorld_spec.rb  
artifacts:  
  files:  
    - '**/*'  
  name: myname-$AWS_REGION

This is an example of an artifact name that uses a CodeBuild environment variable with the artifact's creation date appended to it.

version: 0.2  
phases:  
  build:  
    commands:  
      - rspec HelloWorld_spec.rb  
artifacts:  
  files:  
    - '**/*'  
  name: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>A</mi><mi>W</mi><msub><mi>S</mi><mi>R</mi></msub><mi>E</mi><mi>G</mi><mi>I</mi><mi>O</mi><mi>N</mi><mo>−</mo></mrow><annotation encoding="application/x-tex">AWS_REGION-</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8333em;vertical-align:-0.15em;"></span><span class="mord mathnormal">A</span><span class="mord mathnormal" style="margin-right:0.13889em;">W</span><span class="mord"><span class="mord mathnormal" style="margin-right:0.05764em;">S</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.3283em;"><span style="top:-2.55em;margin-left:-0.0576em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight" style="margin-right:0.00773em;">R</span></span></span></span><span class="vlist-s"></span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">EG</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal" style="margin-right:0.10903em;">ON</span><span class="mord">−</span></span></span></span>(date +%Y-%m-%d)

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

artifacts/discard-paths

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 containsyes, 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 iscom/mycompany/app/HelloWorld.java, specifyingyes will place this file in/HelloWorld.java.

artifacts/base-directory

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:

A single top-level directory (for example,my-directory).
'my-directory*' represents all top-level directories with names starting withmy-directory.

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

artifacts/exclude-paths

Optional mapping. Represents one or more paths, relative tobase-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:

To exclude a file from all directories: "**/`file-name`/**/*"
To exclude all dot folders: "**/.*/**/*"
To exclude all dot files: "**/.*"

artifacts/enable-symlinks

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.

artifacts/s3-prefix

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.

artifacts/secondary-artifacts

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 thesecondaryArtifacts attribute of your project. Each separate definition has the same syntax as the artifacts block above.

Note

The artifacts/files sequence is always required, even when there are only secondary artifacts defined.

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

cache

Optional sequence. Represents information about where CodeBuild can prepare the files for uploading cache to an S3 cache bucket. This sequence is not required if the cache type of the project is No Cache.

cache/key

Optional sequence. Represents the primary key used when search or restore a cache. CodeBuild does an exact match for the primary key.

Here is an example for the key:

key: npm-key-$(codebuild-hash-files package-lock.json) }

cache/fallback-keys

Optional sequence. Represents a list of fallback keys used sequentially when a cache cannot be found using the primary key. Up to five fallback keys are supported, and each is matched using a prefix search. This sequence will be ignored if key is not provided.

Here is an example for the fallback-keys:

fallback-keys:
    - npm-key-$(codebuild-hash-files package-lock.json) }
    - npm-key-
    - npm-

cache/action

Optional sequence. Specifies the action to perform on the cache. Valid values include:

restore which only restores the cache without saving updates.
save which only saves the cache without restoring a previous version.

If no value is provided, CodeBuild defaults to performing both restore and save.

cache/paths

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:

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 namedmy-subdirectory.
`my-subdirectory`/**/* represents all files recursively starting from a subdirectory named my-subdirectory.

Important

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

If you use the AWS CLI, or the AWS SDKs to declare a buildspec when you create or update a build project, the buildspec 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 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 that 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 CodeBuild or 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,buildspec.yml, target/my-app.jar).

Buildspec example

Here is an example of a buildspec.yml file.

version: 0.2

env:
  variables:
    JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"
  parameter-store:
    LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword

phases:
  install:
    commands:
      - echo Entered the install phase...
      - apt-get update -y
      - apt-get install -y maven
    finally:
      - echo This always runs even if the update or install command fails 
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - docker login -u User -p $LOGIN_PASSWORD
    finally:
      - echo This always runs even if the login command fails 
  build:
    commands:
      - echo Entered the build phase...
      - echo Build started on `date`
      - mvn install
    finally:
      - echo This always runs even if the install command fails
  post_build:
    commands:
      - echo Entered the post_build phase...
      - echo Build completed on `date`

reports:
  arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1:
    files:
      - "**/*"
    base-directory: 'target/tests/reports'
    discard-paths: no
  reportGroupCucumberJson:
    files:
      - 'cucumber/target/cucumber-tests.xml'
    discard-paths: yes
    file-format: CUCUMBERJSON # default is JUNITXML
artifacts:
  files:
    - target/messageUtil-1.0.jar
  discard-paths: yes
  secondary-artifacts:
    artifact1:
      files:
        - target/artifact-1.0.jar
      discard-paths: yes
    artifact2:
      files:
        - target/artifact-2.0.jar
      discard-paths: yes
cache:
  paths:
    - '/root/.m2/**/*'

Here is an example of the preceding buildspec, expressed as a single string, for use with the AWS CLI, or the AWS SDKs.

"version: 0.2\n\nenv:\n  variables:\n    JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n  parameter-store:\n    LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n  phases:\n\n  install:\n    commands:\n      - echo Entered the install phase...\n      - apt-get update -y\n      - apt-get install -y maven\n    finally:\n      - echo This always runs even if the update or install command fails \n  pre_build:\n    commands:\n      - echo Entered the pre_build phase...\n      - docker login -u User -p $LOGIN_PASSWORD\n    finally:\n      - echo This always runs even if the login command fails \n  build:\n    commands:\n      - echo Entered the build phase...\n      - echo Build started on `date`\n      - mvn install\n    finally:\n      - echo This always runs even if the install command fails\n  post_build:\n    commands:\n      - echo Entered the post_build phase...\n      - echo Build completed on `date`\n\n reports:\n  reportGroupJunitXml:\n    files:\n      - \"**/*\"\n    base-directory: 'target/tests/reports'\n    discard-paths: false\n  reportGroupCucumberJson:\n    files:\n      - 'cucumber/target/cucumber-tests.xml'\n    file-format: CUCUMBERJSON\n\nartifacts:\n  files:\n    - target/messageUtil-1.0.jar\n  discard-paths: yes\n  secondary-artifacts:\n    artifact1:\n      files:\n       - target/messageUtil-1.0.jar\n      discard-paths: yes\n    artifact2:\n      files:\n       - target/messageUtil-1.0.jar\n      discard-paths: yes\n cache:\n  paths:\n    - '/root/.m2/**/*'"

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

echo Build started on `date` && mvn install

In these examples:

A custom environment variable, in plain text, with the key ofJAVA_HOME and the value of/usr/lib/jvm/java-8-openjdk-amd64, is set.
A custom environment variable named dockerLoginPassword you stored in Amazon EC2 Systems Manager Parameter Store is referenced later in build commands by using the key LOGIN_PASSWORD.
You cannot change these build phase names. The commands that are run in this example are apt-get update -y and apt-get install -y maven (to install Apache Maven), mvn install (to compile, test, and package the source code into a build output artifact and to install the build output artifact in its internal repository), docker login (to sign in to Docker with the password that corresponds to the value of the custom environment variable dockerLoginPassword you set in Amazon EC2 Systems Manager Parameter Store), and several echo commands. Theecho commands are included here to show how 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, CodeBuild uploads the single filemessageUtil-1.0.jar. ThemessageUtil-1.0.jar file can be found in the relative directory named target in the build environment. Becausediscard-paths: yes is specified,messageUtil-1.0.jar is uploaded directly (and not to an intermediate target directory). The file namemessageUtil-1.0.jar and the relative directory name oftarget 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.
reports represents two report groups that generate reports during the build:
- arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 specifies the ARN of a report group. Test results generated by the test framework are in thetarget/tests/reports directory. The file format is JunitXml and the path is not removed from the files that contain test results.
- reportGroupCucumberJson specifies a new report group. If the name of the project is my-project, a report group with the namemy-project-reportGroupCucumberJson is created when a build is run. Test results generated by the test framework are incucumber/target/cucumber-tests.xml. The test file format is CucumberJson and the path is removed from the files that contain test results.

Buildspec versions

The following table lists the buildspec versions and the changes between versions.

Version	Changes
0.2	environment_variables has been renamed toenv. plaintext has been renamed tovariables. The type property for artifacts has been deprecated. In version 0.1, AWS CodeBuild runs each build command in a separate instance of the default shell in the build environment. In version 0.2, CodeBuild runs all build commands in the same instance of the default shell in the build environment.
0.1	This is the initial definition of the build specification format.