# Builds in AWS CodeBuild A *build* represents a set of actions performed by AWS CodeBuild to create output artifacts (for example, a JAR file) based on a set of input artifacts (for example, a collection of Java class files). The following rules apply when you run multiple builds: + When possible, builds run concurrently. The maximum number of concurrently running builds can vary. For more information, see [Quotas for AWS CodeBuild](limits.md). + If the build project has a concurrent build limit set, builds return an error if the number of running builds reaches the concurrent build limit for the project. For more information, see [Enable concurrent build limit](create-project.md#enable-concurrent-build-limit.console). + If the build project does not have a concurrent build limit set, builds are queued if the number of running builds reaches the concurrent build limit for the platform and compute type. The maximum number of builds in a queue is five times the concurrent build limit. For more information, see [Quotas for AWS CodeBuild](limits.md). A build in a queue that does not start after the number of minutes specified in its time out value is removed from the queue. The default timeout value is eight hours. You can override the build queue timeout with a value between five minutes and eight hours when you run your build. For more information, see [Run AWS CodeBuild builds manually](run-build.md). It is not possible to predict the order in which queued builds start. **Note** You can access the history of a build for one year. You can perform these tasks when working with builds: **Topics** + [Run AWS CodeBuild builds manually](run-build.md) + [Run builds on AWS Lambda compute](lambda.md) + [Run builds on reserved capacity fleets](fleets.md) + [Run builds in batches](batch-build.md) + [Execute parallel tests in batch builds](parallel-test.md) + [Cache builds to improve performance](build-caching.md) + [Debug builds in AWS CodeBuild](debug-builds.md) + [Delete builds in AWS CodeBuild](delete-builds.md) + [Retry builds manually in AWS CodeBuild](retry-build.md) + [Retry builds automatically in AWS CodeBuild](auto-retry-build.md) + [Stop builds in AWS CodeBuild](stop-build.md) + [Stop batch builds in AWS CodeBuild](stop-batch-build.md) + [Trigger AWS CodeBuild builds automatically](build-triggers.md) + [View build details in AWS CodeBuild](view-build-details.md) + [View a list of build IDs in AWS CodeBuild](view-build-list.md) + [View a list of build IDs for a build project in AWS CodeBuild](view-builds-for-project.md) # Run AWS CodeBuild builds manually You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in CodeBuild. **Topics** + [Run builds locally with the AWS CodeBuild agent](use-codebuild-agent.md) + [Run a build (console)](run-build-console.md) + [Run a build (AWS CLI)](run-build-cli.md) + [Run a batch build (AWS CLI)](run-batch-build-cli.md) + [Start running builds automatically (AWS CLI)](run-build-cli-auto-start.md) + [Stop running builds automatically (AWS CLI)](run-build-cli-auto-stop.md) + [Run a build (AWS SDKs)](run-build-sdks.md) # Run builds locally with the AWS CodeBuild agent You can use the AWS CodeBuild agent to run CodeBuild builds on a local machine. There are agents available for x86\$164 and ARM platforms. You can also subscribe to receive notifications when new versions of the agent are published. ## Prerequisites Before you begin, you need to do the following: + Install Git on your local machine. + Install and set up [Docker](https://www.docker.com/) on your local machine. ## Set up the build image You only need to set up the build image the first time you run the agent, or when the image has changed. **To set up the build image** 1. If you want to use a curated Amazon Linux 2 image, you can pull it from the CodeBuild public Amazon ECR repository at [https://gallery.ecr.aws/codebuild/amazonlinux-x86\$164-standard](https://gallery.ecr.aws/codebuild/amazonlinux-x86_64-standard) with the following command: ``` $ docker pull public.ecr.aws/codebuild/amazonlinux-x86_64-standard:4.0 ``` Alternatively, if you want to use another Linux image, perform the following steps: 1. Clone the CodeBuild image repo: ``` $ git clone https://github.com/aws/aws-codebuild-docker-images.git ``` 1. Change to the image directory. For this example, use the `aws/codebuild/standard:5.0` image: ``` $ cd aws-codebuild-docker-images/ubuntu/standard/5.0 ``` 1. Build the image. This will take several minutes. ``` $ docker build -t aws/codebuild/standard:5.0 . ``` 1. Download the CodeBuild agent. To download the x86\$164 version of the agent, run the following command: ``` $ docker pull public.ecr.aws/codebuild/local-builds:latest ``` To download the ARM version of the agent, run the following command: ``` $ docker pull public.ecr.aws/codebuild/local-builds:aarch64 ``` 1. The CodeBuild agent is available from [https://gallery.ecr.aws/codebuild/local-builds](https://gallery.ecr.aws/codebuild/local-builds). The Secure Hash Algorithm (SHA) signature for the x86\$164 version of the agent is: ``` sha256:ccb19bdd7af94e4dc761e4c58c267e9455c28ec68d938086b4dc1cf8fe6b0940 ``` The SHA signature for the ARM version of the agent is: ``` sha256:7d7b5d35d2ac4e062ae7ba8c662ffed15229a52d09bd0d664a7816c439679192 ``` You can use the SHA to identify the version of the agent. To see the agent's SHA signature, run the following command and look for the SHA under `RepoDigests`: ``` $ docker inspect public.ecr.aws/codebuild/local-builds:latest ``` ## Run the CodeBuild agent **To run the CodeBuild agent** 1. Change to the directory that contains your build project source. 1. Download the [codebuild\$1build.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script: ``` $ curl -O https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh $ chmod +x codebuild_build.sh ``` 1. Run the `codebuild_build.sh` script and specify your container image and the output directory. To run an x86\$164 build, run the following command: ``` $ ./codebuild_build.sh -i -a ``` To run an ARM build, run the following command: ``` $ ./codebuild_build.sh -i -a -l public.ecr.aws/codebuild/local-builds:aarch64 ``` Replace ** with the name of the container image, such as `aws/codebuild/standard:5.0` or `public.ecr.aws/codebuild/amazonlinux-x86_64-standard:4.0`. The script launches the build image and runs the build on the project in the current directory. To specify the location of the build project, add the `-s ` option to the script command. ## Receive notifications for new CodeBuild agent versions You can subscribe to Amazon SNS notifications so you will be notified when new versions of the AWS CodeBuild agent are released. **To subscribe to CodeBuild agent notifications** 1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home). 1. In the navigation bar, if it's not already selected, change the AWS Region to **US East (N. Virginia)**. You must select this AWS Region because the Amazon SNS notifications that you are subscribing to are created in this Region. 1. In the navigation pane, choose **Subscriptions**. 1. Choose **Create subscription**. 1. In **Create subscription**, do the following: 1. For **Topic ARN**, use the following Amazon Resource Name (ARN): ``` arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates ``` 1. For **Protocol**, choose **Email** or **SMS**. 1. For **Endpoint**, choose where (email or SMS) to receive the notifications. Enter an email or address or phone number, including area code. 1. Choose **Create subscription**. 1. Choose **Email** to receive an email asking you to confirm your subscription. Follow the directions in the email to complete your subscription. If you no longer want to receive these notifications, use the following procedure to unsubscribe. **To unsubscribe from CodeBuild agent notifications** 1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home). 1. In the navigation pane, choose **Subscriptions**. 1. Select the subscription and from **Actions**, choose **Delete subscriptions**. When you are prompted to confirm, choose **Delete**. # Run a build (console) To use AWS CodePipeline to run a build with CodeBuild, skip these steps and follow the instructions in [Use CodeBuild with CodePipeline](how-to-create-pipeline.md). 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. 1. In the list of build projects, choose the build project. 1. You can run the build with the default build project settings, or override build settings for this build only. 1. If you want to run the build with the default build project settings, choose **Start build**. The build starts immediately. 1. If you want to override the default build project settings, choose **Start build with overrides**. In the **Start build** page, you can override the following: + **Build configuration** + **Source** + **Environment variable overrides** If you need to select more advanced overrides, choose **Advanced build overrides**. In this page, you can override the following: + **Build configuration** + **Source** + **Environment** + **Buildspec** + **Artifacts** + **Logs** When you have made your override selections, choose **Start build**. For detailed information about this build, see [View build details (console)](view-build-details.md#view-build-details-console). # Run a build (AWS CLI) **Note** To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Create a pipeline that uses CodeBuild (AWS CLI)](how-to-create-pipeline-cli.md). For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md). 1. Run the `start-build` command in one of the following ways: ``` aws codebuild start-build --project-name ``` Use this if you want to run a build that uses the latest version of the build input artifact and the build project's existing settings. ``` aws codebuild start-build --generate-cli-skeleton ``` Use this if you want to run a build with an earlier version of the build input artifact or if you want to override the settings for the build output artifacts, environment variables, buildspec, or default build timeout period. 1. If you run the **start-build** command with the `--project-name` option, replace ** with the name of the build project, and then skip to step 6 of this procedure. To get a list of build projects, see [View build project names](view-project-list.md). 1. If you run the **start-build** command with the `--idempotency-token` option, a unique case-sensitive identifier or token, is included with the `start-build` request. The token is valid for 5 minutes after the request. If you repeat the `start-build` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error. 1. If you run the **start-build** command with the `--generate-cli-skeleton` option, JSON-formatted data appears in the output. Copy the data to a file (for example, `start-build.json`) in a location on the local computer or instance where the AWS CLI is installed. Modify the copied data to match the following format, and save your results: ``` { "projectName": "projectName", "sourceVersion": "sourceVersion", "artifactsOverride": { "type": "type", "location": "location", "path": "path", "namespaceType": "namespaceType", "name": "artifactsOverride-name", "packaging": "packaging" }, "buildspecOverride": "buildspecOverride", "cacheOverride": { "location": "cacheOverride-location", "type": "cacheOverride-type" }, "certificateOverride": "certificateOverride", "computeTypeOverride": "computeTypeOverride", "environmentTypeOverride": "environmentTypeOverride", "environmentVariablesOverride": { "name": "environmentVariablesOverride-name", "value": "environmentVariablesValue", "type": "environmentVariablesOverride-type" }, "gitCloneDepthOverride": "gitCloneDepthOverride", "imageOverride": "imageOverride", "idempotencyToken": "idempotencyToken", "insecureSslOverride": "insecureSslOverride", "privilegedModeOverride": "privilegedModeOverride", "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", "reportBuildStatusOverride": "reportBuildStatusOverride", "timeoutInMinutesOverride": "timeoutInMinutesOverride", "sourceAuthOverride": "sourceAuthOverride", "sourceLocationOverride": "sourceLocationOverride", "serviceRoleOverride": "serviceRoleOverride", "sourceTypeOverride": "sourceTypeOverride" } ``` Replace the following placeholders: + *projectName*: Required string. The name of the build project to use for this build. + *sourceVersion*: Optional string. A version of the source code to be built, as follows: + For Amazon S3, the version ID that corresponds to the version of the input ZIP file you want to build. If *sourceVersion* is not specified, then the latest version is used. + For CodeCommit, the commit ID that corresponds to the version of the source code you want to build. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used. (You cannot specify a tag name for *sourceVersion*, but you can specify the tag's commit ID.) + For GitHub, the commit ID, pull request ID, branch name, or tag name that corresponds to the version of the source code you want to build. If a pull request ID is specified, it must use the format `pr/pull-request-ID` (for example, `pr/25`). If a branch name is specified, the branch's HEAD commit ID is used. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used. + For Bitbucket, the commit ID, branch name, or tag name that corresponds to the version of the source code you want to build. If a branch name is specified, the branch's HEAD commit ID is used. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used. + The following placeholders are for `artifactsOverride`. + *type*: Optional. The build output artifact type that overrides for this build the one defined in the build project. + *location*: Optional. The build output artifact location that overrides for this build the one defined in the build project. + *path*: Optional. The build output artifact path that overrides for this build the one defined in the build project. + *namespaceType*: Optional. The build output artifact path type that overrides for this build the one defined in the build project. + *name*: Optional. The build output artifact name that overrides for this build the one defined in the build project. + *packaging*: Optional. The build output artifact packaging type that overrides for this build the one defined in the build project. + *buildspecOverride*: Optional. A buildspec declaration that overrides for this build the one defined in the build project. If this value is set, it can be either an inline buildspec definition, the path to an alternate buildspec file relative to the value of the built-in `CODEBUILD_SRC_DIR` environment variable, or the path to an S3 bucket. The S3 bucket must be in the same AWS Region as the build project. Specify the buildspec file using its ARN (for example, `arn:aws:s3:::/buildspec.yml`). If this value is not provided or is set to an empty string, the source code must contain a `buildspec.yml` file in its root directory. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage). + The following placeholders are for `cacheOverride`. + *cacheOverride-location*: Optional. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project. `cacheOverride` is optional and takes a `ProjectCache` object. `location` is required in a `ProjectCache` object. + *cacheOverride-type*: Optional. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project. `cacheOverride` is optional and takes a `ProjectCache` object. `type` is required in a `ProjectCache` object. + *certificateOverride*: Optional. The name of a certificate for this build that overrides the one specified in the build project. + *environmentTypeOverride*: Optional. A container type for this build that overrides the one specified in the build project. The current valid string is `LINUX_CONTAINER`. + The following placeholders are for `environmentVariablesOverride`. + *environmentVariablesOverride-name*: Optional. The name of an environment variable in the build project whose value you want to override for this build. + *environmentVariablesOverride-type*: Optional. The type of environment variable in the build project whose value you want to override for this build. + *environmentVariablesValue*: Optional. The value of the environment variable defined in the build project that you want to override for this build. + *gitCloneDepthOverride*: Optional. The value of the **Git clone depth** in the build project whose value you want to override for this build. If your source type is Amazon S3, this value is not supported. + *imageOverride*: Optional. The name of an image for this build that overrides the one specified in the build project. + *idempotencyToken*: Optional. A string that serves as a token to specify that the build request is idempotent. You can choose any string that is 64 characters or less. The token is valid for 5 minutes after the start-build request. If you repeat the start-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error. + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code. This override applies only if the build's source is GitHub Enterprise Server. + *privilegedModeOverride*: Optional boolean. If set to true, the build overrides privileged mode in the build project. + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out. Its minimum value is five minutes and its maximum value is 480 minutes (eight hours). + *reportBuildStatusOverride*: Optional boolean that specifies whether to send your source provider the status of a build's start and completion. If you set this with a source provider other than GitHub, GitHub Enterprise Server, or Bitbucket, an invalidInputException is thrown. + *sourceAuthOverride*: Optional string. An authorization type for this build that overrides the one defined in the build project. This override applies only if the build project's source is Bitbucket or GitHub. + *sourceLocationOverride*: Optional string. A location that overrides for this build the source location for the one defined in the build project. + *serviceRoleOverride*: Optional string. The name of a service role for this build that overrides the one specified in the build project. + *sourceTypeOverride*: Optional string. A source input type for this build that overrides the source input defined in the build project. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`. + *timeoutInMinutesOverride*: Optional number. The number of build timeout minutes that overrides for this build the one defined in the build project. We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts with `/CodeBuild/` (for example, `/CodeBuild/dockerLoginPassword`). You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager. Choose **Create a parameter**, and then follow the instructions. (In that dialog box, for **KMS key**, you can optionally specify the ARN of an AWS KMS key in your account. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt during retrieval.) If you use the CodeBuild console to create a parameter, the console starts the parameter with `/CodeBuild/` as it is being stored. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**. For more information, see [AWS Systems Manager parameter store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) and [Walkthrough: Create and test a String parameter (console)](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-console.html) in the *Amazon EC2 Systems Manager User Guide*. If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action. If you chose **Create a new service role in your account** earlier, then CodeBuild includes this action in the default service role for your build project automatically. However, if you chose **Choose an existing service role from your account**, then you must include this action in your service role separately. 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 of `my_value`, and you set 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 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 begins with `CODEBUILD_`. This prefix is reserved for internal use. If an environment variable with the same name is defined in multiple places, the environment variable's 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 buildspec file declaration takes lowest precedence. For information about valid values for these placeholders, see [Create a build project (AWS CLI)](create-project.md#create-project-cli). For a list of the latest settings for a build project, see [View build project details](view-project-details.md). 1. Switch to the directory that contains the file you just saved, and run the `start-build` command again. ``` aws codebuild start-build --cli-input-json file://start-build.json ``` 1. If successful, data similar to that described in the [To run the build](getting-started-overview.md#getting-started-run-build-cli) procedure appears in the output. To work with detailed information about this build, make a note of the `id` value in the output, and then see [View build details (AWS CLI)](view-build-details.md#view-build-details-cli). # Run a batch build (AWS CLI) 1. Run the `start-build-batch` command in one of the following ways: ``` aws codebuild start-build-batch --project-name ``` Use this if you want to run a build that uses the latest version of the build input artifact and the build project's existing settings. ``` aws codebuild start-build-batch --generate-cli-skeleton > ``` Use this if you want to run a build with an earlier version of the build input artifact or if you want to override the settings for the build output artifacts, environment variables, buildspec, or default build timeout period. 1. If you run the **start-build-batch** command with the `--project-name` option, replace ** with the name of the build project, and then skip to step 6 of this procedure. To get a list of build projects, see [View build project names](view-project-list.md). 1. If you run the **start-build-batch** command with the `--idempotency-token` option, a unique case-sensitive identifier, or token, is included with the `start-build-batch` request. The token is valid for 5 minutes after the request. If you repeat the `start-build-batch` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error. 1. If you run the **start-build-batch** command with the `--generate-cli-skeleton` option, JSON-formatted data is output to the ** file. This file is similar to the skelton produced by the **start-build** command, with the addition of the following object. For more information about the common objects, see [Run a build (AWS CLI)](run-build-cli.md). Modify this file to add any build overrides, and save your results. ``` "buildBatchConfigOverride": { "combineArtifacts": combineArtifacts, "restrictions": { "computeTypesAllowed": [ allowedComputeTypes ], "maximumBuildsAllowed": maximumBuildsAllowed }, "serviceRole": "batchServiceRole", "timeoutInMins": batchTimeout } ``` The `buildBatchConfigOverride` object is a [ProjectBuildBatchConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectBuildBatchConfig.html) structure that contains the batch build configuration overides for this build. *combineArtifacts* A boolean that specifies if the build artifacts for the batch build should be combined into a single artifact location. *allowedComputeTypes* An array of strings that specify the compute types that are allowed for the batch build. See [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html) for these values. *maximumBuildsAllowed* Specifies the maximum number of builds allowed. *batchServiceRole* Specifies the service role ARN for the batch build project. *batchTimeout* Specifies the maximum amount of time, in minutes, that the batch build must be completed in. 1. Switch to the directory that contains the file you just saved, and run the `start-build-batch` command again. ``` aws codebuild start-build-batch --cli-input-json file://start-build.json ``` 1. If successful, the JSON representation of a [BuildBatch](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_BuildBatch.html) object appears in the console output. See the [StartBuildBatch Response Syntax](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_StartBuildBatch.html#API_StartBuildBatch_ResponseSyntax) for an example of this data. # Start running builds automatically (AWS CLI) If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can use GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository. Run the **create-webhook** command as follows: ``` aws codebuild create-webhook --project-name ``` ** is the name of the build project that contains the source code to be rebuilt. For GitHub, information similar to the following appears in the output: ``` { "webhook": { "url": "" } } ``` ** is the URL to the GitHub webhook. For GitHub Enterprise Server, information similar to the following appears in the output: ![\[Sample output information.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png) 1. Copy the secret key and payload URL from the output. You need them to add a webhook in GitHub Enterprise Server. 1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**. 1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**. # Stop running builds automatically (AWS CLI) If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository. For more information, see [Start running builds automatically (AWS CLI)](run-build-cli-auto-start.md). If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: ``` aws codebuild delete-webhook --project-name ``` + where ** is the name of the build project that contains the source code to be rebuilt. If this command is successful, no information and no errors appear in the output. **Note** This deletes the webhook from your CodeBuild project only. You should also delete the webhook from your GitHub or GitHub Enterprise Server repository. # Run a build (AWS SDKs) To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Use AWS CodeBuild with AWS CodePipeline to test code and run builds](how-to-create-pipeline.md) instead. For information about using CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Run builds on AWS Lambda compute AWS Lambda compute offers optimized start-up speeds for your builds. AWS Lambda supports faster builds due to a lower start-up latency. AWS Lambda also automatically scales, so builds aren’t waiting in queue to run. However, there are some use-cases which AWS Lambda does not support, and if they impact you, use the EC2 compute. For more information, see [Limitations of AWS Lambda compute](#lambda.limitations). **Topics** + [Which tools and runtimes will be included in the curated runtime environment docker images which run on AWS Lambda?](#lambda.tools) + [What if the curated image doesn't include the tools I need?](#lambda.custom) + [Which regions support AWS Lambda compute in CodeBuild?](#lambda.regions) + [Limitations of AWS Lambda compute](#lambda.limitations) + [Deploy a Lambda function using AWS SAM with CodeBuild Lambda Java](sample-lambda-sam-gradle.md) + [Create a single page React app with CodeBuild Lambda Node.js](sample-lambda-react-nodejs.md) + [Update a Lambda function configuration with CodeBuild Lambda Python](sample-lambda-boto3-python.md) ## Which tools and runtimes will be included in the curated runtime environment docker images which run on AWS Lambda? AWS Lambda supports the following tools: AWS CLI v2, AWS SAM CLI, git, go, Java, Node.js, Python, pip, Ruby, and .NET. ## What if the curated image doesn't include the tools I need? If the curated image doesn't include the tools you need, you can provide a custom environment Docker image that includes the necessary tools. **Note** Lambda does not support functions that use multi-architecture container images. For more information, see [Create a Lambda function using a container image ](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html#images-reqs) in the *AWS Lambda Developer Guide*. Note that you require the following Amazon ECR permissions to use custom images for Lambda compute: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:GetAuthorizationToken" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/image-repo" } ] } ``` ------ Also note that `curl` or `wget` must be installed in order to use custom images. ## Which regions support AWS Lambda compute in CodeBuild? In CodeBuild, AWS Lambda compute is supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Mumbai), Asia Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe (Frankfurt), Europe (Ireland), and South America (São Paulo). For more information about AWS Regions where CodeBuild is available, see [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). ## Limitations of AWS Lambda compute There are some use-cases which AWS Lambda does not support, and if they impact you, use the EC2 compute: + AWS Lambda doesn't support tools that require root permissions. For tools such as `yum` or `rpm`, use the EC2 compute type or other tools that don't require root permissions. + AWS Lambda doesn't support Docker builds or runs. + AWS Lambda doesn't support writing to files outside `/tmp`. The included package managers are configured to use the `/tmp` directory by default for downloading and referencing packages. + AWS Lambda doesn't support the environment type `LINUX_GPU_CONTAINER` and isn't supported on Windows Server Core 2019. + AWS Lambda doesn't support caching, custom build timeouts, queue timeout, build badges, privileged mode, custom runtime environments, or runtimes longer than 15 minutes. + AWS Lambda doesn't support VPC connectivity, a fixed range of CodeBuild source IP addresses, EFS, installing certificates, or SSH access with Session Manager. # Deploy a Lambda function using AWS SAM with CodeBuild Lambda Java The AWS Serverless Application Model (AWS SAM) is an open-source framework for building serverless applications. For more information, see the [AWS Serverless Application Model repository](https://github.com/aws/serverless-application-model) on GitHub. The following Java sample uses Gradle to build and test a AWS Lambda function. After which, the AWS SAM CLI is used to deploy the CloudFormation template and deployment bundle. By using CodeBuild Lambda, the build, test, and deployment steps are all handled automatically, allowing for infrastructure to be quickly updated without manual intervention in a single build. ## Set up your AWS SAM repository Create an AWS SAM `Hello World` project using the AWS SAM CLI. **To create your AWS SAM Project** 1. Follow the instructions in the *AWS Serverless Application Model Developer Guide* for [ Installing the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) on your local machine. 1. Run `sam init` and select the following project configuration. ``` Which template source would you like to use?: 1 - AWS Quick Start Templates Choose an AWS Quick Start application template: 1 - Hello World Example Use the most popular runtime and package type? (Python and zip) [y/N]: N Which runtime would you like to use?: 8 - java21 What package type would you like to use?: 1 - Zip Which dependency manager would you like to use?: 1 - gradle Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: N Would you like to enable monitoring using CloudWatch Application Insights? [y/N]: N Would you like to set Structured Logging in JSON format on your Lambda functions? [y/N]: N Project name [sam-app]: ``` 1. Upload the AWS SAM project folder to a supported source repository. For a list of supported source types, see [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html). ## Create a CodeBuild Lambda Java project Create an AWS CodeBuild Lambda Java project and set up the IAM permissions needed for the build. **To create your CodeBuild Lambda Java project** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**. 1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for. 1. In **Source**, select the source repository where your AWS SAM project is located. 1. In **Environment**: + For **Compute**, select **Lambda**. + For **Runtime(s)**, select **Java**. + For **Image**, select **aws/codebuild/amazonlinux-x86\$164-lambda-standard:corretto21**. + For **Service role**, leave **New service role** selected. Make a note of the **Role name**. This will be required when you update the project’s IAM permissions later in this sample. 1. Choose **Create build project**. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** and select the service role associated with your project. You can find your project role in CodeBuild by selecting your build project, choosing **Edit**, **Environment**, and then **Service role**. 1. Choose the **Trust relationships** tab, and then choose **Edit trust policy**. 1. Add the following inline policy to your IAM role. This will be used to deploy your AWS SAM infrastructure later on. For more information, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Action": [ "cloudformation:*", "lambda:*", "iam:*", "apigateway:*", "s3:*" ], "Resource": "arn:aws:iam::*:role/Service*" } ] } ``` ------ ## Set up the project buildspec In order to build, test, and deploy your Lambda function, CodeBuild reads and executes build commands from a buildspec. **To set up your project buildspec** 1. In the CodeBuild console, select your build project, then choose **Edit** and **Buildspec**. 1. In **Buildspec**, choose **Insert build commands** and then **Switch to editor**. 1. Delete the pre-filled build commands and paste in the following buildspec. ``` version: 0.2 env: variables: GRADLE_DIR: "HelloWorldFunction" phases: build: commands: - echo "Running unit tests..." - cd $GRADLE_DIR; gradle test; cd .. - echo "Running build..." - sam build --template-file template.yaml - echo "Running deploy..." - sam package --output-template-file packaged.yaml --resolve-s3 --template-file template.yaml - yes | sam deploy ``` 1. Choose **Update buildspec**. ## Deploy your AWS SAM Lambda infrastructure Use CodeBuild Lambda to automatically deploy your Lambda infrastructure **To deploy your Lambda infrastructure** 1. Choose **Start build**. This will automatically build, test, and deploy your AWS SAM application to AWS Lambda using CloudFormation. 1. Once the build has finished, navigate to the AWS Lambda console and search for your new Lambda function under the AWS SAM project name. 1. Test your Lambda function by selecting **API Gateway** under the **Function** overview, then clicking the **API endpoint** URL. You should see a page open with the message `"message": "hello world"`. ## Clean up your infrastructure To avoid further charges for resources you used during this tutorial, delete the resources created by your AWS SAM template and CodeBuild. **To clean up your infrastructure** 1. Navigate to the CloudFormation console and select the `aws-sam-cli-managed-default`. 1. In **Resources**, empty the deployment bucket `SamCliSourceBucket`. 1. Delete the `aws-sam-cli-managed-default` stack. 1. Delete the CloudFormation stack associated with your AWS SAM project. This stack should have the same name as your AWS SAM project. 1. Navigate to the CloudWatch console and delete the CloudWatch log groups associated with your CodeBuild project. 1. Navigate to the CodeBuild console and delete your CodeBuild project by choosing **Delete build project**. # Create a single page React app with CodeBuild Lambda Node.js [Create React App](https://create-react-app.dev/) is a way to create single-page React applications. The following Node.js sample uses Node.js to build the source artifacts from Create React App and returns the build artifacts. ## Set up your source repository and artifacts bucket Create a source repository for your project using yarn and Create React App. **To set up the source repository and artifacts bucket** 1. On your local machine, run `yarn create react-app ` to create a simple React app. 1. Upload the React app project folder to a supported source repository. For a list of supported source types, see [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html). ## Create a CodeBuild Lambda Node.js project Create an AWS CodeBuild Lambda Node.js project. **To create your CodeBuild Lambda Node.js project** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**. 1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for. 1. In **Source**, select the source repository where your AWS SAM project is located. 1. In **Environment**: + For **Compute**, select **Lambda**. + For **Runtime(s)**, select **Node.js**. + For **Image**, select **aws/codebuild/amazonlinux-x86\$164-lambda-standard:nodejs20**. 1. In **Artifacts**: + For **Type**, select **Amazon S3**. + For **Bucket name**, select the project artifacts bucket you created earlier. + For **Artifacts packaging**, select **Zip**. 1. Choose **Create build project**. ## Set up the project buildspec In order to build your React app, CodeBuild reads and executes build commands from a buildspec file. **To set up your project buildspec** 1. In the CodeBuild console, select your build project, then choose **Edit** and **Buildspec**. 1. In **Buildspec**, choose **Insert build commands** and then **Switch to editor**. 1. Delete the pre-filled build commands and paste in the following buildspec. ``` version: 0.2 phases: build: commands: - yarn - yarn add --dev jest-junit @babel/plugin-proposal-private-property-in-object - yarn run build - yarn run test -- --coverage --watchAll=false --testResultsProcessor="jest-junit" --detectOpenHandles artifacts: name: "build-output" files: - "**/*" reports: test-report: files: - 'junit.xml' file-format: 'JUNITXML' coverage-report: files: - 'coverage/clover.xml' file-format: 'CLOVERXML' ``` 1. Choose **Update buildspec**. ## Build and run your React app Build the React app on CodeBuild Lambda, download the build artifacts, and run the React app locally. **To build and run your React app** 1. Choose **Start build**. 1. Once the build has finished, navigate to your Amazon S3 project artifacts bucket and download the React app artifact. 1. Unzip the React build artifact and `run npm install -g serve && serve -s build` in the project folder. 1. The `serve` command will serve the static site on a local port and print output to your terminal. You can visit the localhost URL under `Local:` in the terminal output to view your React app. To learn more about how to handle deployment for a React based server, see [Create React App Deployment](https://create-react-app.dev/docs/deployment/). ## Clean up your infrastructure To avoid further charges for resources you used during this tutorial, delete the resources created for your CodeBuild project. **To clean up your infrastructure** 1. Delete your project artifacts Amazon S3 bucket 1. Navigate to the CloudWatch console and delete the CloudWatch log groups associated with your CodeBuild project. 1. Navigate to the CodeBuild console and delete your CodeBuild project by choosing **Delete build project**. # Update a Lambda function configuration with CodeBuild Lambda Python The following Python sample uses [Boto3](https://aws.amazon.com/sdk-for-python/) and CodeBuild Lambda Python to update a Lambda function’s configuration. This sample can be extended to manage other AWS resources programmatically. For more information, see [Boto3 documentation](https://aws.amazon.com/sdk-for-python/). ## Prerequisites Create or find a Lambda function in your account. This sample assumes that you have already created a Lambda function in your account and will use CodeBuild to update the Lambda function’s environment variables. For more information on setting up a Lambda function through CodeBuild, see the [Deploy a Lambda function using AWS SAM with CodeBuild Lambda Java](sample-lambda-sam-gradle.md) sample or visit [AWS Lambda](https://aws.amazon.com/lambda/). ## Set up your source repository Create a source repository to store your Boto3 python script. **To set up the source repository** 1. Copy the following python script to a new file called `update_lambda_environment_variables.py`. ``` import boto3 from os import environ def update_lambda_env_variable(lambda_client): lambda_function_name = environ['LAMBDA_FUNC_NAME'] lambda_env_variable = environ['LAMBDA_ENV_VARIABLE'] lambda_env_variable_value = environ['LAMBDA_ENV_VARIABLE_VALUE'] print("Updating lambda function " + lambda_function_name + " environment variable " + lambda_env_variable + " to " + lambda_env_variable_value) lambda_client.update_function_configuration( FunctionName=lambda_function_name, Environment={ 'Variables': { lambda_env_variable: lambda_env_variable_value } }, ) if __name__ == "__main__": region = environ['AWS_REGION'] client = boto3.client('lambda', region) update_lambda_env_variable(client) ``` 1. Upload the python file to a supported source repository. For a list of supported source types, see [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html). ## Create a CodeBuild Lambda Python project Create a CodeBuild Lambda Python project. **To create your CodeBuild Lambda Java project** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**. 1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for. 1. In **Source**, select the source repository where your AWS SAM project is located. 1. In **Environment**: + For **Compute**, select **Lambda**. + For **Runtime(s)**, select **Python**. + For **Image**, select **aws/codebuild/amazonlinux-x86\$164-lambda-standard:python3.12**. + For **Service role**, leave **New service role** selected. Make a note of the **Role name**. This will be required when you update the project’s IAM permissions later in this sample. 1. Choose **Create build project**. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** and select the service role associated with your project. You can find your project role in CodeBuild by selecting your build project, choosing **Edit**, **Environment**, and then **Service role**. 1. Choose the **Trust relationships** tab, and then choose **Edit trust policy**. 1. Add the following inline policy to your IAM role. This will be used to deploy your AWS SAM infrastructure later on. For more information, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "UpdateLambdaPermissions", "Effect": "Allow", "Action": [ "lambda:UpdateFunctionConfiguration" ], "Resource": [ "*" ] } ] } ``` ------ ## Set up the project buildspec In order to update the Lambda function, the script reads environment variables from the buildspec to find the Lambda function’s name, environment variable name, and environment variable value. **To set up your project buildspec** 1. In the CodeBuild console, select your build project, then choose **Edit** and **Buildspec**. 1. In **Buildspec**, choose **Insert build commands** and then **Switch to editor**. 1. Delete the pre-filled build commands and paste in the following buildspec. ``` version: 0.2 env: variables: LAMBDA_FUNC_NAME: "" LAMBDA_ENV_VARIABLE: "FEATURE_ENABLED" LAMBDA_ENV_VARIABLE_VALUE: "true" phases: install: commands: - pip3 install boto3 build: commands: - python3 update_lambda_environment_variables.py ``` 1. Choose **Update buildspec**. ## Update your Lambda configuration Use CodeBuild Lambda Python to automatically update your Lambda function’s configuration. **To update your Lambda function’s configuration** 1. Choose **Start build**. 1. Once the build has finished, navigate to your Lambda function. 1. Select **Configuration** and then **Environment** variables. You should see a new environment variable with key `FEATURE_ENABLED` and value `true`. ## Clean up your infrastructure To avoid further charges for resources you used during this tutorial, delete the resources created for your CodeBuild project. **To clean up your infrastructure** 1. Navigate to the CloudWatch console and delete the CloudWatch log groups associated with your CodeBuild project. 1. Navigate to the CodeBuild console and delete your CodeBuild project by choosing **Delete build project**. 1. If you created a Lambda function for the purpose of this sample, choose **Actions** and **Delete function** to clean up your Lambda function. ## Extensions If you want to extend this sample to manage other AWS resources using AWS CodeBuild Lambda Python: + Update the Python script to modify the new resources using Boto3. + Update the IAM role associated with your CodeBuild project to have permissions for the new resources. + Add any new environment variables associated with the new resources to your buildspec. # Run builds on reserved capacity fleets CodeBuild offers the following compute fleets: + On-demand fleets + Reserved capacity fleets With on-demand fleets, CodeBuild provides compute for your builds. The machines are destroyed when the build finishes. On-demand fleets are fully managed, and includes automatic scaling capabilities to handle spikes in demand. **Note** On-demand fleets do not support macOS. CodeBuild also offers reserved capacity fleets which contain instances powered by Amazon EC2 that are maintained by CodeBuild. With reserved capacity fleets, you configure a set of dedicated instances for your build environment. These machines remain idle, ready to process builds or tests immediately and reduces build durations. With reserved capacity fleets, your machines are always running and will continue to incur costs as long they're provisioned. **Important** Regardless of how long you run an instance for, reserved capacity fleets incur an initial charge per instance, after which there may be additional associated costs. For more information, see [https://aws.amazon.com/codebuild/pricing/](https://aws.amazon.com/codebuild/pricing/). **Topics** + [Create a reserved capacity fleet](#fleets.how-to) + [Best practices](#fleets.best-practices) + [Can I share a reserved capacity fleet across multiple CodeBuild projects?](#fleets.share) + [How does attribute-based compute work?](#fleets.attribute-compute) + [Can I manually specify an Amazon EC2 instance for my fleet?](#fleets.manual-input-compute) + [Which regions support reserved capacity fleets?](#fleets.regions) + [How do I configure a reserved capacity macOS fleet?](#fleets.configure-macos) + [How do I configure a custom Amazon Machine Image (AMI) for a reserved capacity fleet?](#fleets.custom-ami) + [Limitations of reserved capacity fleets](#fleets.limitations) + [Reserved capacity fleet properties](fleets.reserved-capacity-fleets.md) + [Reserved capacity samples with AWS CodeBuild](reserved-capacity-samples.md) ## Create a reserved capacity fleet Use the following instructions to create a reserved capacity fleet. **To create a reserved capacity fleet** 1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Compute fleets**, and then choose **Create Fleet**. 1. In the **Compute fleet name** text field, enter a name for your fleet. 1. From the **Operating system** drop-down menu, choose the operating system. 1. From the **Architecture** drop-down menu, choose the architecture. 1. (Optional) Select **Use instance running mode - optional** to run on an Amazon EC2 instance directly instead of a Docker container. Then choose a **Major version** and **Minor version**. 1. (Optional) In **Additional configuration** do the following: + Select **Configure VPC - optional** to connect your fleet to a VPC to access private resources during usage. + From the **VPC** drop-down menu, select a VPC that your CodeBuild fleet will access. + From the **Subnets** drop-down menu, select the subnets that CodeBuild should use to set up your VPC configuration. + From the **Security groups** drop-down menu, select the security groups that CodeBuild should use to work with your VPC. + In the **Fleet Service Role** field, choose an existing service role. **Note** Make sure that your fleet role has the necessary permissions. For more information, see [Allow a user to add a permission policy for a fleet service role](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role). + If you chose the Amazon Linux operating system, select **Define proxy configurations - optional** to apply network access control for your reserved capacity instances. + For **Default behavior**, choose to allow or deny outgoing traffic to all destinations by default. + For **Proxy rules**, choose **Add proxy rule** to specify destination domains or IPs to allow or deny network access control to. + Select **Configure custom AMI - optional** to use a custom Amazon Machine Image (AMI). + From the **AMI** drop-down menu, select a an Amazon Machine Image (AMI) for your fleet. + In the **Fleet Service Role** field, choose an existing service role. **Note** Make sure that your fleet role has the necessary permissions. For more information, see [Allow a user to add a permission policy for a fleet service role](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role). 1. In **Capacity configuration**, from **Compute selection mode**, choose one of the following: + If you choose **Guided selection**, do the following: + For **Compute**, choose the type of instances included in this fleet. + In the **Capacity** text field, enter the minimum number of instances in the fleet. + (Optional) In **Additional configuration** do the following: + Select **Configure scaling - optional** to automatically scale your fleet based on this configuration. From the **Scaling mode - optional** drop-down menu, choose the behavior when demand exceeds the fleet capacity. + If you choose **Custom instance**, do the following: + From the **Compute instance type** drop-down menu, select the type of instances included in this fleet. + In the **Additional EBS volume size - optional** text field, enter the volume additional to the 64GB of disk space provided. + In the **Capacity** text field, enter the minimum number of instances in the fleet. + (Optional) In **Additional configuration** do the following: + Select **Configure scaling - optional** to automatically scale your fleet based on this configuration. From the **Scaling mode - optional** drop-down menu, choose the behavior when demand exceeds the fleet capacity. 1. Choose **Create compute fleet**. 1. After the compute fleet is created, create a new CodeBuild project or edit an existing one. From **Environment**, choose **Reserved capacity** under **Provisioning model**, and then choose the specified fleet under **Fleet name**. ## Best practices When using reserved capacity fleets, we recommend that you follow these best practices. + We recommend using source cache mode to help improve the build performance by caching the source. + We recommend using Docker layer caching to help improve the build performance by caching existing Docker layers. ## Can I share a reserved capacity fleet across multiple CodeBuild projects? Yes, you can maximize the utilization of a fleet's capacity by using it across multiple projects. **Important** When using the reserved capacity feature, data cached on fleet instances, including source files, Docker layers, and cached directories specified in the buildspec, can be accessible to other projects within the same account. This is by design and allows projects within the same account to share fleet instances. ## How does attribute-based compute work? If you choose `ATTRIBUTE_BASED_COMPUTE` as your fleet's `computeType`, you can specify the attributes in a new field called `computeConfiguration`. These attributes include vCPUs, memory, disk space, and the `machineType`. This `machineType` is either `GENERAL` or `NVME`. After specifying one or some of the available attributes, CodeBuild will choose a compute type from the available supported instance types as the finalized `computeConfiguration`. **Note** CodeBuild will choose the cheapest instance that match all input requirements. The chosen instances' memory, vCPUs, and disk space will all be greater than or equal to the input requirements. You can check the resolved `computeConfiguration` in the created or updated fleet. If you input a `computeConfiguration` that is not possible to satisfy in CodeBuild, you'll receive a validation exception. Also note that on-demand fleet overflow behavior will be overridden to queue behavior if the `computeConfiguration` is not available for on-demand. ## Can I manually specify an Amazon EC2 instance for my fleet? Yes, you can directly input your desired Amazon EC2 instance in the console by selecting **Custom instance** or by configuring the API parameter, `InstanceType`. This field is used in the following APIs: CreateFleet, UpdateFleet, CreateProject, UpdateProject and StartBuild. For more information, see [Compute instance type](fleets.reserved-capacity-fleets.md#compute). ## Which regions support reserved capacity fleets? Reserved capacity Amazon Linux and Windows fleets are supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Mumbai), Asia Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe (Frankfurt), Europe (Ireland), and South America (São Paulo). For more information about AWS Regions where CodeBuild is available, see [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). Reserved capacity macOS Medium fleets are supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Sydney), and Europe (Frankfurt). Reserved capacity macOS Large fleets are supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), and Asia Pacific (Sydney). ## How do I configure a reserved capacity macOS fleet? **To configure a reserved capacity macOS fleet** 1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Compute fleets**, and then choose **Create Fleet**. 1. In the **Compute fleet name** text field, enter a name for your fleet. 1. From the **Operating system** drop-down menu, choose **macOS**. 1. In the **Compute** field, choose one of the following compute machine types: **Apple M2, 24 GB memory, 8 vCPUs** or **Apple M2, 32 GB memory, 12 vCPUs**. 1. In the **Capacity** text field, enter the minimum number of instances in the fleet. 1. (Optional) To use a custom image for your fleet, see [How do I configure a custom Amazon Machine Image (AMI) for a reserved capacity fleet?](#fleets.custom-ami) to ensure that your Amazon Machine Image (AMI) has the required prerequisites. 1. (Optional) To configure a VPC with your fleet, in **Additional configuration** do the following: + From the **VPC - optional** drop-down menu, select a VPC that your CodeBuild fleet will access. + From the **Subnets** drop-down menu, select the subnets that CodeBuild should use to set up your VPC configuration. + From the **Security groups** drop-down menu, select the security groups that CodeBuild should use to work with your VPC. + In the **Fleet service role** field, choose an existing service role. **Note** Make sure that your fleet role has the necessary permissions. For more information, see [Allow a user to add a permission policy for a fleet service role](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role). 1. Choose **Create compute fleet** and wait for the fleet instance to launch. Once launched the capacity will be `n/n`, where *n* is the capacity provided. 1. After the compute fleet has launched, create a new CodeBuild project or edit an existing one. From **Environment**, choose **Reserved capacity** under **Provisioning model**, and then choose the specified fleet under **Fleet name**. ## How do I configure a custom Amazon Machine Image (AMI) for a reserved capacity fleet? **To configure a custom Amazon Machine Image (AMI) for a reserved capacity fleet** 1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Compute fleets**, and then choose **Create Fleet**. 1. In the **Compute fleet name** text field, enter a name for your fleet. 1. Choose **Custom image** for your fleet and ensure that your Amazon Machine Image (AMI) has the following prerequisites: + If your environment type is `MAC_ARM`, make sure that your AMI **Architecture** is 64-bit `Mac-Arm`. + If your environment type is `LINUX_EC2`, make sure that your AMI **Architecture** is 64-bit `x86`. + If your environment type is `ARM_EC2`, make sure that your AMI **Architecture** is 64-bit `Arm`. + If your environment type is `WINDOWS_EC2`, make sure that your AMI **Architecture** is 64-bit `x86`. + The AMI allows the CodeBuild service **Organization ARN**. For a list of Organization ARNs, see [Amazon Machine Images (AMI)](fleets.reserved-capacity-fleets.md#ami). + If the AMI is encrypted with a AWS KMS key, the AWS KMS key must also allow the CodeBuild service **Organization ID**. For a list of Organization IDs, see [Amazon Machine Images (AMI)](fleets.reserved-capacity-fleets.md#ami). For more information on AWS KMS keys, see [ Allow organizations and OUs to use a KMS key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html#allow-org-ou-to-use-key) in the *Amazon EC2 User Guide*. To give CodeBuild organization permission to use a KMS key, add the following statement to the key policy: ``` { "Sid": "Allow access for organization root", "Effect": "Allow", "Principal": "*", "Action": [ "kms:Describe*", "kms:List*", "kms:Get*", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant" ], "Resource": "*", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-123example" } } } ``` + In the **Fleet service role** field, grant the following Amazon EC2 permissions: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:DescribeImages", "ec2:DescribeSnapshots" ], "Resource": "*" } ] } ``` ------ ## Limitations of reserved capacity fleets There are some use-cases which reserved capacity fleets do not support, and if they impact you, use on-demand fleets instead: + Reserved capacity fleets don't support build utilization metrics. + Reserved capacity macOS fleets don't support debug session. For more information on limits and quotas, see [Compute fleets](limits.md#fleet-limits). # Reserved capacity fleet properties A reserved capacity fleet contains the following properties. For more information about reserved capacity fleets, see [Run builds on reserved capacity fleets](fleets.md). **Operating system** The operating system. The following operating systems are available: + Amazon Linux + macOS + Windows Server 2019 + Windows Server 2022 **Architecture** The processor architecture. The following architectures are available: + x86\$164 + Arm64 **Environment type** The environment types available when **Amazon Linux** is selected. The following environment types are available: + Linux EC2 + Linux GPU **Compute instance type** The compute configurations for fleet instances. **Guided selection** Specify different compute types by selecting vCPU, memory and disk space settings. For information about compute type availability by region, see [About reserved capacity environment types](build-env-ref-compute-types.md#environment-reserved-capacity.types). **Custom instance** Manually specify the desired instance type. **Capacity** The initial number of machines allocated to the fleet, which defines the number of builds that can run in parallel. **Overflow behavior** Defines the behavior when the number of builds exceeds the fleet capacity. **On-demand** Overflow builds run on CodeBuild on-demand. If you choose to set your overflow behavior to on-demand while creating a VPC-connected fleet, make sure that you add the required VPC permissions to your project service role. For more information, see [Example policy statement to allow CodeBuild access to AWS services required to create a VPC network interface](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-vpc-network-interface). If you choose to set your overflow behavior to on-demand, note that overflow builds will be billed separately, similar to on-demand Amazon EC2. For more information, see [https://aws.amazon.com/codebuild/pricing/](https://aws.amazon.com/codebuild/pricing/). **Queue** Build runs are placed in a queue until a machine is available. This limits additional costs because no additional machines are allocated. **Amazon Machine Images (AMI)** The Amazon Machine Image (AMI) properties for your fleet. The following properties are supported by CodeBuild: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/fleets.reserved-capacity-fleets.html) **Additional configuration** **VPC - optional** The VPC that your CodeBuild fleet will access. For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md). If a fleet override is specified when calling the StartBuild API, CodeBuild will ignore the project VPC configuration. **Subnets** The VPC subnets that CodeBuild uses to set up your VPC configuration. Note that reserved capacity fleets support only one subnet in a single Availablity Zone. Also, ensure that your subnets include a NAT gateway. **Security groups** The VPC security groups that CodeBuild uses with your VPC. Ensure that your security groups allow outbound connections. **Fleet Service Role** Defines the service role for your fleet from an existing service role in your account. **Define proxy configurations - optional** Proxy configurations that apply network access control to your reserved capacity instances. For more information, see [Use AWS CodeBuild with a managed proxy server](run-codebuild-in-managed-proxy-server.md). Proxy configurations don't support VPC, Windows, or MacOS. **Default behavior** Defines the behavior of outgoing traffic. **Allow** Allows outgoing traffic to all destinations by default. **Deny** Denies outgoing traffic to all destinations by default. **Proxy rules** Specifies destination domains or IPs to allow or deny network access control to. # Reserved capacity samples with AWS CodeBuild These samples can be used to experiment with reserved capacity fleets in CodeBuild. **Topics** + [Caching with reserved capacity sample](#reserved-capacity-samples.caching) ## Caching with reserved capacity sample A cache can store reusable pieces of your build environment and use them across multiple builds. This sample demonstrated how to enable caching within your build project using reserved capacity. For more information, see [Cache builds to improve performance](build-caching.md). You can start by specifying one or more cache modes in your project settings: ``` Cache: Type: LOCAL Modes: - LOCAL_CUSTOM_CACHE - LOCAL_DOCKER_LAYER_CACHE - LOCAL_SOURCE_CACHE ``` **Note** Make sure to enable privileged mode in order to use Docker layer cache. Your project buildspec settings should look like the following: ``` version: 0.2 phases: build: commands: - echo testing local source cache - touch /codebuild/cache/workspace/foobar.txt - git checkout -b cached_branch - echo testing local docker layer cache - docker run alpine:3.14 2>&1 | grep 'Pulling from' || exit 1 - echo testing local custom cache - touch foo - mkdir bar && ln -s foo bar/foo2 - mkdir bar/bar && touch bar/bar/foo3 && touch bar/bar/foo4 - "[ -f foo ] || exit 1" - "[ -L bar/foo2 ] || exit 1" - "[ -f bar/bar/foo3 ] || exit 1" - "[ -f bar/bar/foo4 ] || exit 1" cache: paths: - './foo' - './bar/**/*' - './bar/bar/foo3' ``` You can start by running a build with the new project to seed the cache. Once that's complete, you should start another build with an overriding buildspec, similar to the following: ``` version: 0.2 phases: build: commands: - echo testing local source cache - git branch | if grep 'cached_branch'; then (exit 0); else (exit 1); fi - ls /codebuild/cache/workspace | if grep 'foobar.txt'; then (exit 0); else (exit 1); fi - echo testing local docker layer cache - docker run alpine:3.14 2>&1 | if grep 'Pulling from'; then (exit 1); else (exit 0); fi - echo testing local custom cache - "[ -f foo ] || exit 1" - "[ -L bar/foo2 ] || exit 1" - "[ -f bar/bar/foo3 ] || exit 1" - "[ -f bar/bar/foo4 ] || exit 1" cache: paths: - './foo' - './bar/**/*' - './bar/bar/foo3' ``` # Run builds in batches You can use AWS CodeBuild to run concurrent and coordinated builds of a project with batch builds. **Topics** + [Security role](#batch_security_role) + [Batch build types](#batch_build_types) + [Batch report mode](#batch-report-mode) + [More information](#batch_more_info) ## 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: **Topics** + [Build graph](#batch_build_graph) + [Build list](#batch_build_list) + [Build matrix](#batch_build_matrix) + [Build fanout](#batch_build_fanout) ### 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: variables: BUILD_ID: build1 ignore-failure: false - identifier: build2 buildspec: build2.yml env: variables: BUILD_ID: build2 depend-on: - build1 - identifier: build3 env: variables: BUILD_ID: build3 depend-on: - build2 - identifier: build4 env: compute-type: ARM_LAMBDA_1GB - identifier: build5 env: fleet: fleet_name ``` 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`](batch-build-buildspec.md#build-spec.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 `build1` and `build2` builds will run in parallel. ``` batch: fast-fail: false build-list: - identifier: build1 env: variables: BUILD_ID: build1 ignore-failure: false - identifier: build2 buildspec: build2.yml env: variables: BUILD_ID: build2 ignore-failure: true - identifier: build3 env: compute-type: ARM_LAMBDA_1GB - identifier: build4 env: fleet: fleet_name - identifier: build5 env: compute-type: GENERAL_LINUX_XLAGRE ``` For more information about the build list buildspec syntax, see [`batch/build-list`](batch-build-buildspec.md#build-spec.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 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/amazonlinux-x86_64-standard:4.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`](batch-build-buildspec.md#build-spec.batch.build-matrix). ### Build fanout A build fanout defines a task that will be split into multiple builds in the batch. This can be used for running tests in parallel. CodeBuild creates a separate build for each shard of test cases based on the value set in `parallelism` field. The following example defines a build fanout that creates five builds that run in parallel. ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - npm install build: commands: - mkdir -p test-results - cd test-results - | codebuild-tests-run \ --test-command 'npx jest --runInBand --coverage' \ --files-search "codebuild-glob-search '**/test/**/*.test.js'" \ --sharding-strategy 'equal-distribution' ``` In this example, assuming that there are 100 tests that needs to be run, CodeBuild creates five builds that each runs 20 tests in parallel. For more information about the build graph buildspec syntax, see [`batch/build-fanout`](batch-build-buildspec.md#build-spec.batch.build-fanout). ## Batch report mode If the source provider for your project is Bitbucket, GitHub, or GitHub Enterprise, and your project is configured to report build statuses to the source provider, you can select how you want your batch build statuses sent to the source provider. You can select to have the statuses sent as a single aggregate status report for the batch, or have the status of each build in the batch reported individually. For more information, see the following topics: + [Batch configuration (create)](create-project.md#create-project-console-batch-config) + [Batch configuration (update)](change-project.md#change-project-console-batch-config) ## More information For more information, see the following topics: + [Batch build buildspec reference](batch-build-buildspec.md) + [Batch configuration](create-project.md#create-project-console-batch-config) + [Run a batch build (AWS CLI)](run-batch-build-cli.md) + [Stop batch builds in AWS CodeBuild](stop-batch-build.md) # Execute parallel tests in batch builds You can use AWS CodeBuild to execute parallel tests in batch builds. Parallel test execution is a testing approach where multiple test cases run simultaneously across different environments, machines, or browsers, rather than executing sequentially. This approach can significantly reduce overall test execution time and improve testing efficiency. In CodeBuild, you can split your tests across multiple environments and run them concurrently. The key advantages of parallel test execution include: 1. **Reduced execution time** - Tests that would take hours sequentially can complete in minutes. 1. **Better resource utilization** - Makes efficient use of available computing resources. 1. **Earlier feedback** - Faster test completion means quicker feedback to developers. 1. **Cost-effective** - Saves both time and computing costs in the long run. When implementing parallel test execution, two main approaches are commonly considered: separate environments and multithreading. While both methods aim to achieve concurrent test execution, they differ significantly in their implementation and effectiveness. Separate environments create isolated instances where each test suite runs independently, while multithreading executes multiple tests simultaneously within the same process space using different threads. The key advantages of separate environments over multithreading include: 1. **Isolation** - Each test runs in a completely isolated environment, preventing interference between tests. 1. **Resource conflicts** - No competition for shared resources that often occurs in multithreading. 1. **Stability** - Less prone to race conditions and synchronization issues. 1. **Easier debugging** - When tests fail, it's simpler to identify the cause as each environment is independent. 1. **State management** - Easily manage shared state issues that plague multithreaded tests. 1. **Better scalability** - Can easily add more environments without complexity. **Topics** + [Support in AWS CodeBuild](#parallel-test-support) + [Enable parallel test execution in batch builds](parallel-test-enable.md) + [Use the `codebuild-tests-run` CLI command](parallel-test-tests-run.md) + [Use the `codebuild-glob-search` CLI command](parallel-test-glob-search.md) + [About test splitting](parallel-test-splitting.md) + [Automatically merge individual build reports](parallel-test-auto-merge.md) + [Parallel test execution for various test frameworks sample](sample-parallel-test.md) ## Support in AWS CodeBuild AWS CodeBuild provides robust support for parallel test execution through its batch build feature, specifically designed to leverage separate environment execution. This implementation aligns perfectly with the benefits of isolated testing environments. **Batch build with test distribution** CodeBuild's batch build functionality enables the creation of multiple build environments that run simultaneously. Each environment operates as a completely isolated unit, with its own compute resources, runtime environment, and dependencies. Through the batch build configuration, you can specify how many parallel environments they need and how tests should be distributed across them. **Test sharding CLI** CodeBuild includes a built-in test distribution mechanism through its CLI tool, `codebuild-tests-run`, which automatically divides tests into different environments. **Report aggregation** One of the key strengths of CodeBuild's implementation is its ability to handle test result aggregation seamlessly. While tests execute in separate environments, CodeBuild automatically collects and combines the test reports from each environment into a unified test report at the batch build level. This consolidation provides a comprehensive view of test results while maintaining the efficiency benefits of parallel execution. The following is the diagram explains the complete concept of parallel test execution in AWS CodeBuild. ![\[Concept diagram of parallel test execution.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/parallel-test.png) # Enable parallel test execution in batch builds To run tests in parallel, update the batch build buildspec file to include the build-fanout field and the number of parallel builds to split the test suite in the `parallelism` field as shown below. The `parallelism` field specifies how many independent executors are setup to execute the test suite. To run the tests in multiple parallel execution environments, set the `parallelism` field to a value greater than zero. In example below, `parallelism` is set to five, meaning CodeBuild starts five identical builds that executes a portion of the test suite in parallel. You can use the [codebuild-tests-run](parallel-test-tests-run.md) CLI command to split and run your tests. Your test files will be split up, and a portion of your tests run in each build. This reduces the overall time taken to run the full test suite. In the following example, tests will be split up into five and the split points are calculated based on name of the tests. ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - npm install jest-junit --save-dev pre_build: commands: - echo 'prebuild' build: commands: - | codebuild-tests-run \ --test-command 'npx jest --runInBand --coverage' \ --files-search "codebuild-glob-search '**/_tests_/**/*.test.js'" \ --sharding-strategy 'equal-distribution' post_build: commands: - codebuild-glob-search '**/*.xml' - echo "Running post-build steps..." - echo "Build completed on `date`" reports: test-reports: files: - '**/junit.xml' base-directory: . discard-paths: yes file-format: JUNITXML ``` If reports are configured for build-fanout build, then the test reports are generated for each build separately, which can be viewed under the **Reports** tab of the corresponding builds in the AWS CodeBuild console. For more information on how to execute parallel tests in batch, see [Parallel test execution for various test frameworks sample](sample-parallel-test.md). # Use the `codebuild-tests-run` CLI command AWS CodeBuild provides CLI that will take test command and test file location as input. The CLI with these input will split the tests into number of shards as specified in the `parallelism` field based on test file names. The assignment of test files to shard is decided by the sharding strategy. ``` codebuild-tests-run \ --files-search "codebuild-glob-search '**/__tests__/*.js'" \ --test-command 'npx jest --runInBand --coverage' \ --sharding-strategy 'equal-distribution' ``` The following table describes the fields for the `codebuild-tests-run` CLI command. | Field name | Type | Required or optional | Definition | | --- | --- | --- | --- | | `test-command` | String | Required | This command is used for running the tests. | | `files-search` | String | Required | This command gives a list of test files. You can use the AWS CodeBuild provided [codebuild-glob-search](parallel-test-glob-search.md) CLI command or any other file search tool of your choice. Ensure that the `files-search` command outputs file names, each separated by a new line. | | `sharding-strategy` | Enum | Optional | Valid values: `equal-distribution` (default), `stability` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/parallel-test-tests-run.html) For more information, see [About test splitting](parallel-test-splitting.md). | The `codebuild-tests-run` CLI works first to identify the list of test files using the command provided in the `files-search` parameter. It then determines a subset of test files designated for the current shard (environment) using the specified sharding strategy. Finally, this subset of test files is formatted into a space-separated list and appended to the end of the command provided in the `test-command` parameter before being executed. For test frameworks that don't accept space-separated lists, the `codebuild-tests-run` CLI provides a flexible alternative through the `CODEBUILD_CURRENT_SHARD_FILES` environment variable. This variable contains a newline-separated list of test file paths designated for the current build shard. By leveraging this environment variable, you can easily adapt to various test framework requirements, accommodating those that expect input formats different from space-separated lists. Moreover, you can also format the test file names as per need of test framework. The following is an example of the use of `CODEBUILD_CURRENT_SHARD_FILES` on Linux with the Django framework. Here `CODEBUILD_CURRENT_SHARD_FILES` is used to get *dot notation* file paths supported by Django: ``` codebuild-tests-run \ —files-search "codebuild-glob-search '/tests/test_.py'" \ —test-command 'python3 manage.py test $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed -E "s/\//__/g; s/\.py$//; s/__/./g")' \ —sharding-strategy 'equal-distribution' ``` **Note** Note that the `CODEBUILD_CURRENT_SHARD_FILES` environment variable can be used only inside the scope of the `codebuild-tests-run` CLI. Also, if you are using `CODEBUILD_CURRENT_SHARD_FILES` inside test-command, put `CODEBUILD_CURRENT_SHARD_FILES` inside double quotes as shown in above example. # Use the `codebuild-glob-search` CLI command AWS CodeBuild provides a built-in CLI tool called `codebuild-glob-search` that allows you to search for files in your working directory based on one or more glob patterns. This tool can be particularly useful when you want to run tests on specific files or directories within your project. ## Usage The `codebuild-glob-search` CLI has the following usage syntax: ``` codebuild-glob-search [ ...] ``` + ``, ``, etc.: One or more glob patterns to match against the files in your working directory. + `*`: Matches any sequence of characters (excluding path separators). + `**`: Matches any sequence of characters (including path separators). **Note** Ensure that the glob string has quotes. To check the results of pattern-matching, use the `echo` command. ``` version: 0.2 phases: build: commands: - echo $(codebuild-glob-search '**/__tests__/*.js') - codebuild-glob-search '**/__tests__/*.js' | xargs -n 1 echo ``` ## Output The CLI will output a newline-separated list of file paths that match the provided glob patterns. The file paths returned will be relative to the working directory. If no files are found matching the provided patterns, the CLI will output a message indicating that no files were found. Note that directories found due to any given pattern will be excluded from the search results. ## Example If you want to search only for files inside the tests directory and its subdirectories with a `.js` extension, you can use the following command with the `codebuild-glob-search` CLI: ``` codebuild-glob-search '**/__tests__/*.js' ``` This command will search for all files with a `.js` extension inside the `__tests__`directory and its subdirectories, as denoted by the pattern. # About test splitting AWS CodeBuild's test splitting feature allows you to parallelize your test suite execution across multiple compute instances, reducing the overall test run time. This feature is enabled through the batch configuration in your CodeBuild project settings and the `codebuild-tests-run`utility in your buildspec file. The tests are split based on the sharding strategy specified. CodeBuild provides two sharding strategies as specified below: Equal-distribution The `equal-distribution` sharding strategy divides the tests across parallel builds based on the alphabetical order of the test file names. This approach first sorts the test files and then employs a chunk-based method to distribute them, ensuring that similar files are grouped together for testing. It is recommended when dealing with a relatively small set of test files. While this method aims to allocate an approximately equal number of files to each shard, with a maximum difference of one, it does not guarantee stability. When test files are added or removed in subsequent builds, the distribution of existing files may change, potentially causing reassignment across shards. Stability The `stability` sharding strategy employs a consistent hashing algorithm to split tests among shards, ensuring that file distribution remains stable. When new files are added or removed, this approach ensures that the existing file-to-shard assignments remain largely unchanged. For large test suites, it is recommended to use the stability option to evenly distribute the tests across shards. This mechanism aims to provide a near-equal distribution, ensuring that each shard receives a similar number of files, with only minimal variance. While the stability strategy does not guarantee an ideal equal distribution, it offers a near-equal distribution that maintains consistency in file assignments across builds, even as files are added or removed. To enable test splitting, you need to configure the batch section in your CodeBuild project settings, specifying the desired `parallelism` level and other relevant parameters. Additionally, you'll need to include the `codebuild-tests-run` utility in your buildspec file, along with the appropriate test commands and splitting method. # Automatically merge individual build reports In fanout batch builds, AWS CodeBuild supports automatic merging of individual build reports into a consolidated batch-level report. This feature provides a comprehensive view of test results and code coverage across all builds within a batch. ## How it works When executing `fanout` batch builds, each individual build generates [test reports](test-reporting.md). CodeBuild then automatically consolidates identical reports from different builds into a unified report, which is attached to the batch build. These consolidated reports are readily accessible through the [ BatchGetBuildBatches](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_BatchGetBuildBatches.html#CodeBuild-BatchGetBuildBatches-response-buildBatches) API's `reportArns` field, and can also be viewed in the **Reports** tab of the console. This merging capability extends to auto-discovered reports as well. Consolidated reports are created under [report groups](test-report-group.md) that are either specified in the buildspec or auto-discovered by CodeBuild. You can analyze trends of the merged reports directly under these report groups, providing valuable insights into the overall build performance and quality metrics across historical builds of the same build-batch project. For each individual build within the batch, CodeBuild automatically creates separate report groups. These follow a specific naming convention, combining the batch build report group name with a suffix of `BuildFanoutShard`, where the `shard_number` represents the number of the shard in which the report group is created. This organization allows you to track and analyze trends at both the consolidated and individual build levels, providing flexibility in how you monitor and evaluate their build processes. The batch-build report follows the same structure as [individual build reports](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Report.html). The following key fields in the **Report** tab are specific to batch-build reports: **Batch build report status** The status of batch build reports follows specific rules depending on the report type: + Test reports: + Succeeded: Status is set to succeeded when all individual build reports have succeeded. + Failed: Status is set to failed if any individual build report has failed. + Incomplete: Status is marked as incomplete if any individual build report is missing or has an incomplete status. + Code coverage reports: + Complete: Status is set to complete when all individual build reports are complete. + Failed: Status is set to failed if any individual build report has failed. + Incomplete: Status is marked as incomplete if any individual build report is missing or has an incomplete status. **Test summary** The merged test report consolidates the following fields from all individual build reports: + duration-in-nano-seconds: Maximum test duration time in nanoseconds among all individual build reports. + total: The combined count of all test cases, summing the total number of tests from each build. + status-counts: Provides a consolidated view of test statuses such as passed, failed, or skipped, calculated by aggregating the count of each status type across all individual builds. **Code coverage summary** The merged code coverage report combines fields from all individual builds using the following calculations: + branches-covered: Sum of all covered branches from individual reports. + branches-missed: Sum of all missed branches from individual reports. + branch-coverage-percentage: `(Total covered branches / Total branches) * 100` + lines-covered: Sum of all covered lines from individual reports. + lines-missed: Sum of all missed lines from individual reports. + lines-coverage-percentage: `(Total covered lines / Total lines) * 100` **Execution ID** The batch build ARN. **Test cases** The merged report contains a consolidated list of all test cases from individual builds, accessible through both the [DescribeTestCases](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_DescribeTestCases.html) API and the batch build report in the console. **Code coverages** The merged code coverage report provides consolidated line and branch coverage information for each file across all individual builds, accessible through both the [DescribeCodeCoverages](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_DescribeCodeCoverages.html) API and the batch build report in the console. Note: For files covered by multiple test files distributed across different shards, the merged report uses the following selection criteria: 1. Primary selection is based on the highest line coverage among shards. 1. If line coverage is equal across multiple shards, the shard with the highest branch coverage is selected. # Parallel test execution for various test frameworks sample You can use the `codebuild-tests-run` CLI command to split and run your tests across parallel execution environments. The following section provides `buildspec.yml` samples for various frameworks, illustrating the usage of the `codebuild-tests-run` command. + Each example below includes a `parallelism` level of five, meaning that five identical execution environments will be created to split your tests across. You can choose a `parallelism` level to suit your project by modifying the `parallelism` value in the `build-fanout` section. + Each example below shows configuring your tests to be split by the test file name, which is by default. This distributes the tests evenly across the parallel execution environments. Before you get started, see [Execute parallel tests in batch builds](parallel-test.md) for more information. For a full list of options when using the `codebuild-tests-run` CLI command, see [Use the `codebuild-tests-run` CLI command](parallel-test-tests-run.md). **Topics** + [Configure parallel tests with Django](sample-parallel-test-django.md) + [Configure parallel tests with Elixir](sample-parallel-test-elixir.md) + [Configure parallel tests with Go](sample-parallel-test-go.md) + [Configure parallel tests with Java (Maven)](sample-parallel-test-java-maven.md) + [Configure parallel tests with Javascript (Jest)](sample-parallel-test-javascript.md) + [Configure parallel tests with Kotlin](sample-parallel-test-kotlin.md) + [Configure parallel tests with PHPUnit](sample-parallel-test-phpunit.md) + [Configure parallel tests with Pytest](sample-parallel-test-python.md) + [Configure parallel tests with Ruby (Cucumber)](sample-parallel-test-ruby-cucumber.md) + [Configure parallel tests with Ruby (RSpec)](sample-parallel-test-ruby.md) # Configure parallel tests with Django The following is sample of a `buildspec.yml` that shows parallel test execution with Django on an Ubuntu platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 phases: install: commands: - echo 'Installing Python dependencies' - sudo yum install -y python3 python3-pip - python3 -m ensurepip --upgrade - python3 -m pip install django pre_build: commands: - echo 'Prebuild' build: commands: - echo 'Running Django Tests' - | codebuild-tests-run \ --test-command 'python3 manage.py test $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed -E "s/\//__/g; s/\.py$//; s/__/./g")' \ --files-search "codebuild-glob-search '**/tests/*test_*.py'" \ --sharding-strategy 'equal-distribution' post_build: commands: - echo 'Test execution completed' ``` The above example shows the usage of the environment variable `CODEBUILD_CURRENT_SHARD_FILES`. Here `CODEBUILD_CURRENT_SHARD_FILES` is used to fetch dot notation file paths supported by Django. Use `CODEBUILD_CURRENT_SHARD_FILES` inside double quotes as shown above. # Configure parallel tests with Elixir The following is sample of a `buildspec.yml` that shows parallel test execution with Elixir on an Ubuntu platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 phases: install: commands: - echo 'Installing Elixir dependencies' - sudo apt update - sudo DEBIAN_FRONTEND=noninteractive apt install -y elixir - elixir --version - mix --version pre_build: commands: - echo 'Prebuild' build: commands: - echo 'Running Elixir Tests' - | codebuild-tests-run \ --test-command 'mix test' \ --files-search "codebuild-glob-search '**/test/**/*_test.exs'" \ --sharding-strategy 'equal-distribution' post_build: commands: - echo "Test execution completed" ``` # Configure parallel tests with Go The following is sample of a `buildspec.yml` that shows parallel test execution with Go on an Linux platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Fetching Go version' - go version pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running go Tests' - go mod init calculator - cd calc - | codebuild-tests-run \ --test-command "go test -v calculator.go" \ --files-search "codebuild-glob-search '**/*test.go'" post_build: commands: - echo "Test execution completed" ``` In above example, `calculator.go` function contains simple mathematical functions to test and all test files and `calculator.go` file is inside `calc` folder. # Configure parallel tests with Java (Maven) The following is sample of a `buildspec.yml` that shows parallel test execution with Java on an Linux platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: pre_build: commands: - echo 'prebuild' build: commands: - echo "Running mvn test" - | codebuild-tests-run \ --test-command 'mvn test -Dtest=$(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed "s|src/test/java/||g; s/\.java//g; s|/|.|g; s/ /,/g" | tr "\n" "," | sed "s/,$//")' \ --files-search "codebuild-glob-search '**/test/**/*.java'" post_build: commands: - echo "Running post-build steps..." - echo "Test execution completed" ``` In the given example, the environment variable `CODEBUILD_CURRENT_SHARD_FILES` contains test files in the current shard, separated by newlines. These files are converted into a comma-separated list of class names in the format accepted by the `-Dtest` parameter for Maven. # Configure parallel tests with Javascript (Jest) The following is sample of a `buildspec.yml` that shows parallel test execution with Javascript on an Ubuntu platform: ``` version: 0.2 batch: fast-fail: true build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Installing Node.js dependencies' - apt-get update - apt-get install -y nodejs - npm install - npm install --save-dev jest-junit pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running JavaScript Tests' - | codebuild-tests-run \ --test-command "npx jest" \ --files-search "codebuild-glob-search '**/test/**/*.test.js'" \ --sharding-strategy 'stability' post_build: commands: - echo 'Test execution completed' ``` # Configure parallel tests with Kotlin The following is sample of a `buildspec.yml` that shows parallel test execution with Kotlin on an Linux platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 2 ignore-failure: false phases: install: runtime-versions: java: corretto11 commands: - echo 'Installing dependencies' - KOTLIN_VERSION="1.8.20" # Replace with your desired version - curl -o kotlin-compiler.zip -L "https://github.com/JetBrains/kotlin/releases/download/v${KOTLIN_VERSION}/kotlin-compiler-${KOTLIN_VERSION}.zip" - unzip kotlin-compiler.zip -d /usr/local - export PATH=$PATH:/usr/local/kotlinc/bin - kotlin -version - curl -O https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone/1.8.2/junit-platform-console-standalone-1.8.2.jar pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running Kotlin Tests' - | codebuild-tests-run \ --test-command 'kotlinc src/main/kotlin/*.kt $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | tr "\n" " ") -d classes -cp junit-platform-console-standalone-1.8.2.jar' \ --files-search "codebuild-glob-search 'src/test/kotlin/*.kt'" - | codebuild-tests-run \ --test-command ' java -jar junit-platform-console-standalone-1.8.2.jar --class-path classes \ $(for file in $CODEBUILD_CURRENT_SHARD_FILES; do class_name=$(basename "$file" .kt) echo "--select-class $class_name" done) ' \ --files-search "codebuild-glob-search 'src/test/kotlin/*.kt'" post_build: commands: - echo "Test execution completed" ``` In the above example, the `codebuild-tests-run` CLI is used twice. During the first run, kotlinc compiles the files. The `CODEBUILD_CURRENT_SHARD_FILES` variable retrieves the test files assigned to the current shard, which are then converted into a space-separated list. In the second run, JUnit executes the tests. Again, `CODEBUILD_CURRENT_SHARD_FILES` fetches the test files assigned to the current shard, but this time they are converted into class names. # Configure parallel tests with PHPUnit The following is sample of a `buildspec.yml` that shows parallel test execution with PHPUnit on an Linux platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Install dependencies' - composer require --dev phpunit/phpunit pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running phpunit Tests' - composer dump-autoload - | codebuild-tests-run \ --test-command "./vendor/bin/phpunit --debug" \ --files-search "codebuild-glob-search '**/tests/*Test.php'" post_build: commands: - echo 'Test execution completed' ``` # Configure parallel tests with Pytest The following is sample of a `buildspec.yml` that shows parallel test execution with Pytest on an Ubuntu platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Installing Python dependencies' - apt-get update - apt-get install -y python3 python3-pip - pip3 install --upgrade pip - pip3 install pytest build: commands: - echo 'Running Python Tests' - | codebuild-tests-run \ --test-command 'python -m pytest' \ --files-search "codebuild-glob-search 'tests/test_*.py'" \ --sharding-strategy 'equal-distribution' post_build: commands: - echo "Test execution completed" ``` The following is sample of a `buildspec.yml` that shows parallel test execution with Pytest on an Windows platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Installing Python dependencies' - pip install pytest pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running pytest' - | & codebuild-tests-run ` --test-command 'pytest @("$env:CODEBUILD_CURRENT_SHARD_FILES" -split \"`r?`n\")' ` --files-search "codebuild-glob-search '**/test_*.py' '**/*_test.py'" ` --sharding-strategy 'equal-distribution' post_build: commands: - echo "Test execution completed" ``` In above example, `CODEBUILD_CURRENT_SHARD_FILES` environment variable is used to fetch test files assigned to current shard and passed as array to pytest command. # Configure parallel tests with Ruby (Cucumber) The following is sample of a `buildspec.yml` that shows parallel test execution with Cucumber on an Linux platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Installing Ruby dependencies' - gem install bundler - bundle install pre_build: commands: - echo 'prebuild' build: commands: - echo 'Running Cucumber Tests' - cucumber --init - | codebuild-tests-run \ --test-command "cucumber" \ --files-search "codebuild-glob-search '**/*.feature'" post_build: commands: - echo "Test execution completed" ``` # Configure parallel tests with Ruby (RSpec) The following is sample of a `buildspec.yml` that shows parallel test execution with RSpec on an Ubuntu platform: ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - echo 'Installing Ruby dependencies' - apt-get update - apt-get install -y ruby ruby-dev build-essential - gem install bundler - bundle install build: commands: - echo 'Running Ruby Tests' - | codebuild-tests-run \ --test-command 'bundle exec rspec' \ --files-search "codebuild-glob-search 'spec/**/*_spec.rb'" \ --sharding-strategy 'equal-distribution' post_build: commands: - echo "Test execution completed" ``` # Cache builds to improve performance You can save time when your project builds by using a cache. A cache can store reusable pieces of your build environment and use them across multiple builds. Your build project can use one of two types of caching: Amazon S3 or local. If you use a local cache, you must choose one or more of three cache modes: source cache, Docker layer cache, and custom cache. **Note** Docker layer cache mode is available for the Linux environment only. If you choose this mode, you must run your build in privileged mode. CodeBuild projects granted privileged mode grants its container access to all devices. For more information, see [Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website. **Topics** + [Amazon S3 caching](caching-s3.md) + [Local caching](caching-local.md) + [Specify a local cache](specify-caching-local.md) # Amazon S3 caching Amazon S3 caching stores the cache in an Amazon S3 bucket that is available across multiple build hosts. This is a good option for small to intermediate sized build artifacts that are more expensive to build than to download. To use Amazon S3 in a build, you can specify the paths for the files you want to cache in `buildspec.yml`. CodeBuild will automatically store and update the cache to the Amazon S3 location configured on the project. If you don't specify the file paths, CodeBuild will best-effort cache common language dependencies to help you speed up the builds. You can view the cache details in the build logs. Additionally, if you want to have multiple versions of cache, you can define a cache key in the `buildspec.yml`. CodeBuild stores the cache under the context of this cache key, and create a unique cache copy that will not be updated once created. The cache keys can be shared across projects as well. Features such as dynamic keys, cache versioning, and cache sharing across builds are only available when a key is specified. To learn more about the cache syntax in buildspec file, see [cache](build-spec-ref.md#build-spec.cache) in the buildspec reference. **Topics** + [Generate dynamic keys](#caching-s3-dynamic) + [codebuild-hash-files](#caching-s3-dynamic.codebuild-hash-files) + [Cache version](#caching-s3-version) + [Cache sharing between projects](#caching-s3-sharing) + [Buildspec examples](#caching-s3-examples) ## Generate dynamic keys A cache key can include shell commands and environment variables to make it unique, enabling automatic cache updates when key changes. For example, you can define a key using the hash of the `package-lock.json` file. When the dependencies in that file change, the hash—and therefore the cache key—changes, triggering the automatic creation of a new cache. ``` cache: key: npm-key-$(codebuild-hash-files package-lock.json) ``` CodeBuild will evaluate the expression `$(codebuild-hash-files package-lock.json)` to get the final key: ``` npm-key-abc123 ``` You can also define a cache key using environment variables, such as `CODEBUILD_RESOLVED_SOURCE_VERSION`. This ensures that whenever your source changes, a new key is generated, resulting in a new cache being saved automatically: ``` cache: key: npm-key-$CODEBUILD_RESOLVED_SOURCE_VERSION ``` CodeBuild will evaluate the expression and get the final key: ``` npm-key-046e8b67481d53bdc86c3f6affdd5d1afae6d369 ``` ## codebuild-hash-files `codebuild-hash-files` is a CLI tool that calculates a SHA-256 hash for a set of files in the CodeBuild source directory using glob patterns: ``` codebuild-hash-files ... ``` Here are some examples using `codebuild-hash-files`: ``` codebuild-hash-files package-lock.json codebuild-hash-files '**/*.md' ``` ## Cache version The cache version is a hash generated from the paths of the directories being cached. If two caches have different versions, they are treated as distinct caches during the matching process. For example, the following two caches are considered different because they reference different paths: ``` version: 0.2 phases: build: commands: - pip install pandas==2.2.3 --target pip-dependencies cache: key: pip-dependencies paths: - "pip-dependencies/**/*" ``` ``` version: 0.2 phases: build: commands: - pip install pandas==2.2.3 --target tmp/pip-dependencies cache: key: pip-dependencies paths: - "tmp/pip-dependencies/**/*" ``` ## Cache sharing between projects You can use the `cacheNamespace` API field under the `cache` section to share a cache across multiple projects. This field defines the scope of the cache. To share a cache, must do the following: + Use the same `cacheNamespace`. + Specify the same cache `key`. + Define identical cache paths. + Use the same Amazon S3 buckets and `pathPrefix` if set. This ensures consistency and enables cache sharing across projects. ### Specify a cache namespace (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Choose **Create project**. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). 1. In **Artifacts**, choose **Additional configuration**. 1. For **Cache type**, choose **Amazon S3**. 1. For **Cache namespace - optional**, enter a namespace value. ![\[Cache namespace parameter in the CodeBuild console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/s3-cache-namespace.png) 1. Continue with the default values and then choose **Create build project**. ### Specify a cache namespace (AWS CLI) You can use the the `--cache` parameter in the AWS CLI to specify a cache namespace. ``` --cache '{"type": "S3", "location": "your-s3-bucket", "cacheNamespace": "test-cache-namespace"}' ``` ## Buildspec examples Here are several buildspec examples for common languages: **Topics** + [Cache Node.js dependencies](#caching-s3-examples.nodejs) + [Cache Python dependencies](#caching-s3-examples.python) + [Cache Ruby dependencies](#caching-s3-examples.ruby) + [Cache Go dependencies](#caching-s3-examples.go) ### Cache Node.js dependencies If your project includes a `package-lock.json` file and uses `npm` to manage Node.js dependencies, the following example shows how to set up caching. By default, `npm` installs dependencies into the `node_modules` directory. ``` version: 0.2 phases: build: commands: - npm install cache: key: npm-$(codebuild-hash-files package-lock.json) paths: - "node_modules/**/*" ``` ### Cache Python dependencies If your project includes a `requirements.txt` file and uses pip to manage Python dependencies, the following example demonstrates how to configure caching. By default, pip installs packages into the system's `site-packages` directory. ``` version: 0.2 phases: build: commands: - pip install -r requirements.txt cache: key: python-$(codebuild-hash-files requirements.txt) paths: - "/root/.pyenv/versions/${python_version}/lib/python${python_major_version}/site-packages/**/*" ``` Additionally, you can install dependencies into a specific directory and configure caching for that directory. ``` version: 0.2 phases: build: commands: - pip install -r requirements.txt --target python-dependencies cache: key: python-$(codebuild-hash-files requirements.txt) paths: - "python-dependencies/**/*" ``` ### Cache Ruby dependencies If your project includes a `Gemfile.lock` file and uses `Bundler` to manage gem dependencies, the following example demonstrates how to configure caching effectively. ``` version: 0.2 phases: build: commands: - bundle install --path vendor/bundle cache: key: ruby-$(codebuild-hash-files Gemfile.lock) paths: - "vendor/bundle/**/*" ``` ### Cache Go dependencies If your project includes a `go.sum` file and uses Go modules to manage dependencies, the following example demonstrates how to configure caching. By default, Go modules are downloaded and stored in the `${GOPATH}/pkg/mod` directory. ``` version: 0.2 phases: build: commands: - go mod download cache: key: go-$(codebuild-hash-files go.sum) paths: - "/go/pkg/mod/**/*" ``` # Local caching Local caching stores a cache locally on a build host that is available to that build host only. This is a good option for intermediate to large build artifacts because the cache is immediately available on the build host. This is not the best option if your builds are infrequent. This means that build performance is not impacted by network transfer time. If you choose local caching, you must choose one or more of the following cache modes: + Source cache mode caches Git metadata for primary and secondary sources. After the cache is created, subsequent builds pull only the change between commits. This mode is a good choice for projects with a clean working directory and a source that is a large Git repository. If you choose this option and your project does not use a Git repository (AWS CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket), the option is ignored. + Docker layer cache mode caches existing Docker layers. This mode is a good choice for projects that build or pull large Docker images. It can prevent the performance issues caused by pulling large Docker images down from the network. **Note** You can use a Docker layer cache in the Linux environment only. The `privileged` flag must be set so that your project has the required Docker permissions. By default, Docker daemon is enabled for non-VPC builds. If you would like to use Docker containers for VPC builds, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website and enable privileged mode. Also, Windows does not support privileged mode. You should consider the security implication before you use a Docker layer cache. + Custom cache mode caches directories you specify in the buildspec file. This mode is a good choice if your build scenario is not suited to one of the other two local cache modes. If you use a custom cache: + Only directories can be specified for caching. You cannot specify individual files. + Symlinks are used to reference cached directories. + Cached directories are linked to your build before it downloads its project sources. Cached items overrides source items if they have the same name. Directories are specified using cache paths in the buildspec file. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax). + Avoid directory names that are the same in the source and in the cache. Locally-cached directories may override, or delete the contents of, directories in the source repository that have the same name. **Note** Local caching is not supported with the `LINUX_GPU_CONTAINER` environment type and the `BUILD_GENERAL1_2XLARGE` compute type. For more information, see [Build environment compute modes and types](build-env-ref-compute-types.md). **Note** Local caching is not supported when you configure CodeBuild to work with a VPC. For more information on using VPCs with CodeBuild, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md). # Specify a local cache You can use the AWS CLI, console, SDK, or CloudFormation to specify a local cache. For more information about local caching, see [Local caching](caching-local.md). **Topics** + [Specify local caching (CLI)](#caching-local-cli) + [Specify local caching (console)](#caching-local-console) + [Specify local caching (CloudFormation)](#caching-local-cfn) ## Specify local caching (CLI) You can use the the `--cache` parameter in the AWS CLI to specify each of the three local cache types. + To specify a source cache: ``` --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE] ``` + To specify a Docker layer cache: ``` --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE] ``` + To specify a custom cache: ``` --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] ``` For more information, see [Create a build project (AWS CLI)](create-project.md#create-project-cli). ## Specify local caching (console) You specify a cache in the **Artifacts** section of the console. For **Cache type**, choose **Amazon S3** or **Local**. If you choose **Local**, choose one or more of the three local cache options. ![\[Specify a local cache by choosing one or more of the three local cache options.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.png) For more information, see [Create a build project (console)](create-project.md#create-project-console). ## Specify local caching (CloudFormation) If you use CloudFormation to specify a local cache, on the `Cache` property, for `Type`, specify `LOCAL`. The following sample YAML-formatted CloudFormation code specifies all three local cache types. You can specify any combination of the types. If you use a Docker layer cache, under `Environment`, you must set `PrivilegedMode` to `true` and `Type` to `LINUX_CONTAINER`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: Artifacts: Type: S3 Location: Name: myArtifact EncryptionDisabled: true OverrideArtifactName: true Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Certificate: # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE PrivilegedMode: true Source: Type: GITHUB Location: InsecureSsl: true GitCloneDepth: 1 ReportBuildStatus: false TimeoutInMinutes: 10 Cache: Type: LOCAL Modes: # You can specify one or more cache mode, - LOCAL_CUSTOM_CACHE - LOCAL_DOCKER_LAYER_CACHE - LOCAL_SOURCE_CACHE ``` **Note** By default, Docker daemon is enabled for non-VPC builds. If you would like to use Docker containers for VPC builds, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website and enable privileged mode. Also, Windows does not support privileged mode. For more information, see [Create a build project (CloudFormation)](create-project.md#create-project-cloud-formation). # Debug builds in AWS CodeBuild AWS CodeBuild provides two methods for debugging builds during development and troubleshooting. You can use the CodeBuild Sandbox environment to investigate issues and validate fixes in real-time, or you can use AWS Systems Manager Session Manager to connect to the build container and view the container state. ## Debug builds with CodeBuild sandbox The CodeBuild sandbox environment provides an interactive debug session in a secure and isolated environment. You can interact with the environment directly through the AWS Management Console or AWS CLI, execute commands, and validate your build process step by step. It uses a cost-effective per-second billing model and supports the same native integration with source providers and AWS services as your build environment. You can also connect to a sandbox environment using SSH clients or from your integrated development environments (IDEs). To learn more about the CodeBuild sandbox pricing, visit the [CodeBuild pricing documentation](https://aws.amazon.com/codebuild/pricing/#Sandbox). For detailed instructions, visit the [Debug builds with CodeBuild sandbox](sandbox.md) documentation. ## Debug builds with Session Manager AWS Systems Manager Session Manager enables direct access to running builds in their actual execution environment. This approach allows you to connect to active build containers and inspect the build process in real-time. You can examine the file system, monitor running processes, and troubleshoot issues as they occur. For detailed instructions, visit the [Debug builds with Session Manager](session-manager.md) documentation. # Debug builds with CodeBuild sandbox In AWS CodeBuild, you can debug a build by using CodeBuild sandbox to run custom commands and troubleshoot your build. **Topics** + [Prerequisites](#sandbox-prereq) + [Debug builds with CodeBuild sandbox (console)](#sandbox-console) + [Debug builds with CodeBuild sandbox (AWS CLI)](#sandbox-cli) + [Tutorial: Connecting to a sandbox using SSH](sandbox-ssh-tutorial.md) + [Troubleshooting AWS CodeBuild sandbox SSH connection issues](sandbox-troubleshooting.md) ## Prerequisites Before using a CodeBuild sandbox, make sure that your CodeBuild service role has the following SSM policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ssm:StartSession" ], "Resource": [ "arn:aws:codebuild:us-east-1:111122223333:build/*", "arn:aws:ssm:us-east-1::document/AWS-StartSSHSession" ] } ] } ``` ------ ## Debug builds with CodeBuild sandbox (console) Use the following instructions to run commands and connect your SSH client with CodeBuild sandbox in the console. ### Run commands with CodeBuild sandbox (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. Choose the build project, and then choose **Debug build**. ![\[The debug build project detail page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/sandbox-debug-build.png) 1. In the **Run command** tab, enter your custom commands, and then choose **Run command**. ![\[The run command detail page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/debug-build-run.png) 1. Your CodeBuild sandbox will then be initialized and start running your custom commands. The output will be shown in the **Output** tab when it's completed. ![\[The run command output page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/debug-build-run-output.png) 1. When troubleshooting is completed, you can stop the sandbox by choosing **Stop sandbox**. Then choose **Stop** to confirm that your sandbox will be stopped. ![\[The stop sandbox dialog box.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/stop-sandbox.png) ![\[The run command output page with a stopped sandbox in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/stopped-sandbox.png) ### Connect to your SSH client with CodeBuild sandbox (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. Choose the build project, and then choose **Debug build**. ![\[The debug build project detail page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/sandbox-debug-build.png) 1. In the **SSH Client** tab and choose **Start sandbox**. ![\[The SSH client sandbox page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ssh-client-sandbox.png) 1. After the CodeBuild sandbox starts running, follow the console instructions to connect your SSH client with the sandbox. ![\[The SSH client sandbox page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ssh-client-sandbox-terminal.png) 1. When troubleshooting is completed, you can stop the sandbox by choosing **Stop sandbox**. Then choose **Stop** to confirm that your sandbox will be stopped. ![\[The stop sandbox dialog box.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/stop-sandbox-2.png) ![\[The run command output page with a stopped sandbox in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/stopped-sandbox-2.png) ## Debug builds with CodeBuild sandbox (AWS CLI) Use the following instructions to run commands and connect your SSH client with CodeBuild sandbox. ### Start a CodeBuild sandbox (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild start-sandbox --project-name $PROJECT_NAME ``` + `--project-name` : CodeBuild project name ------ #### [ Sample request ] ``` aws codebuild start-sandbox --project-name "project-name" ``` ------ #### [ Sample response ] ``` { "id": "project-name", "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name", "projectName": "project-name", "requestTime": "2025-02-06T11:24:15.560000-08:00", "status": "QUEUED", "source": { "type": "S3", "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip", "insecureSsl": false }, "environment": { "type": "LINUX_CONTAINER", "image": "aws/codebuild/standard:6.0", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [{ "name": "foo", "value": "bar", "type": "PLAINTEXT" }, { "name": "bar", "value": "baz", "type": "PLAINTEXT" } ], "privilegedMode": false, "imagePullCredentialsType": "CODEBUILD" }, "timeoutInMinutes": 10, "queuedTimeoutInMinutes": 480, "logConfig": { "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } }, "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey", "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole", "currentSession": { "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "currentPhase": "QUEUED", "status": "QUEUED", "startTime": "2025-02-06T11:24:15.626000-08:00", "logs": { "groupName": "group", "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } } } ``` ------ ### Get information about the sandbox status (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild batch-get-sandboxes --ids $SANDBOX_IDs ``` ------ #### [ Sample request ] ``` aws codebuild stop-sandbox --id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name" ``` + `--ids` : Comma separated list of `sandboxIds` or `sandboxArns`. You can either provide a sandbox ID or a sandbox ARN: + Sandbox ID: `:` For example, `project-name:d25be134-05cb-404a-85da-ac5f85d2d72c`. + Sandbox ARN: arn:aws:codebuild:**:**:sandbox/**:** For example, `arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name:d25be134-05cb-404a-85da-ac5f85d2d72c`. ------ #### [ Sample response ] ``` { "sandboxes": [{ "id": "project-name", "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name", "projectName": "project-name", "requestTime": "2025-02-06T11:24:15.560000-08:00", "endTime": "2025-02-06T11:39:21.587000-08:00", "status": "STOPPED", "source": { "type": "S3", "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip", "insecureSsl": false }, "environment": { "type": "LINUX_CONTAINER", "image": "aws/codebuild/standard:6.0", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [{ "name": "foo", "value": "bar", "type": "PLAINTEXT" }, { "name": "bar", "value": "baz", "type": "PLAINTEXT" } ], "privilegedMode": false, "imagePullCredentialsType": "CODEBUILD" }, "timeoutInMinutes": 10, "queuedTimeoutInMinutes": 480, "logConfig": { "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } }, "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey", "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole", "currentSession": { "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "currentPhase": "COMPLETED", "status": "STOPPED", "startTime": "2025-02-06T11:24:15.626000-08:00", "endTime": "2025-02-06T11:39:21.600000-08:00", "phases": [{ "phaseType": "SUBMITTED", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-06T11:24:15.577000-08:00", "endTime": "2025-02-06T11:24:15.606000-08:00", "durationInSeconds": 0 }, { "phaseType": "QUEUED", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-06T11:24:15.606000-08:00", "endTime": "2025-02-06T11:24:16.067000-08:00", "durationInSeconds": 0 }, { "phaseType": "PROVISIONING", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-06T11:24:16.067000-08:00", "endTime": "2025-02-06T11:24:20.519000-08:00", "durationInSeconds": 4, "contexts": [{ "statusCode": "", "message": "" }] }, { "phaseType": "DOWNLOAD_SOURCE", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-06T11:24:20.519000-08:00", "endTime": "2025-02-06T11:24:22.238000-08:00", "durationInSeconds": 1, "contexts": [{ "statusCode": "", "message": "" }] }, { "phaseType": "RUNNING_SANDBOX", "phaseStatus": "TIMED_OUT", "startTime": "2025-02-06T11:24:22.238000-08:00", "endTime": "2025-02-06T11:39:21.560000-08:00", "durationInSeconds": 899, "contexts": [{ "statusCode": "BUILD_TIMED_OUT", "message": "Build has timed out. " }] }, { "phaseType": "COMPLETED", "startTime": "2025-02-06T11:39:21.560000-08:00" } ], "logs": { "groupName": "group", "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } } }], "sandboxesNotFound": [] } ``` ------ ### Stop a sandbox (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild stop-sandbox --id $SANDBOX-ID ``` + `--id` : A `sandboxId` or `sandboxArn`. ------ #### [ Sample request ] ``` aws codebuild stop-sandbox --id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name" ``` ------ #### [ Sample response ] ``` { "id": "project-name", "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name", "projectName": "project-name", "requestTime": "2025-02-06T11:24:15.560000-08:00", "status": "STOPPING", "source": { "type": "S3", "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip", "insecureSsl": false }, "environment": { "type": "LINUX_CONTAINER", "image": "aws/codebuild/standard:6.0", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [{ "name": "foo", "value": "bar", "type": "PLAINTEXT" }, { "name": "bar", "value": "baz", "type": "PLAINTEXT" } ], "privilegedMode": false, "imagePullCredentialsType": "CODEBUILD" }, "timeoutInMinutes": 10, "queuedTimeoutInMinutes": 480, "logConfig": { "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } }, "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey", "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole", "currentSession": { "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "currentPhase": "RUN_SANDBOX", "status": "STOPPING", "startTime": "2025-02-06T11:24:15.626000-08:00", "phases": [{ "phaseType": "SUBMITTED", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-08T14:33:26.144000-08:00", "endTime": "2025-02-08T14:33:26.173000-08:00", "durationInSeconds": 0 }, { "phaseType": "QUEUED", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-08T14:33:26.173000-08:00", "endTime": "2025-02-08T14:33:26.702000-08:00", "durationInSeconds": 0 }, { "phaseType": "PROVISIONING", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-08T14:33:26.702000-08:00", "endTime": "2025-02-08T14:33:30.530000-08:00", "durationInSeconds": 3, "contexts": [{ "statusCode": "", "message": "" }] }, { "phaseType": "DOWNLOAD_SOURCE", "phaseStatus": "SUCCEEDED", "startTime": "2025-02-08T14:33:30.530000-08:00", "endTime": "2025-02-08T14:33:33.478000-08:00", "durationInSeconds": 2, "contexts": [{ "statusCode": "", "message": "" }] }, { "phaseType": "RUN_SANDBOX", "startTime": "2025-02-08T14:33:33.478000-08:00" } ], "logs": { "groupName": "group", "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } } } ``` ------ ### Start a command execution (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild start-command-execution --command $COMMAND --type $TYPE --sandbox-id $SANDBOX-ID ``` + `--command` : The command that needs to be executed. + `--sandbox-id` : A `sandboxId` or `sandboxArn`. + `--type` : The command type, `SHELL`. ------ #### [ Sample request ] ``` aws codebuild start-command-execution --command "echo "Hello World"" --type SHELL --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name ``` ------ #### [ Sample response ] ``` { "id": "e1c658c2-02bb-42a8-9abb-94835241fcd6", "sandboxId": "f7126a4a-b0d5-452f-814c-fea73718f805", "submitTime": "2025-02-06T20:12:02.683000-08:00", "status": "SUBMITTED", "command": "echo \"Hello World\"", "type": "SHELL", "logs": { "groupName": "group", "streamName": "stream", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/f7126a4a-b0d5-452f-814c-fea73718f805.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/f7126a4a-b0d5-452f-814c-fea73718f805.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } } ``` ------ ### Get information about the command executions (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild batch-get-command-executions --command-execution-ids $COMMAND-IDs --sandbox-id $SANDBOX-IDs ``` + `--command-execution-ids` : Comma separated list of `commandExecutionIds`. + `--sandbox-id` : A `sandboxId` or `sandboxArn`. ------ #### [ Sample request ] ``` aws codebuild batch-get-command-executions --command-execution-ids"c3c085ed-5a8f-4531-8e95-87d547f27ffd" --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name" ``` ------ #### [ Sample response ] ``` { "commandExecutions": [{ "id": "c3c085ed-5a8f-4531-8e95-87d547f27ffd", "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05", "submitTime": "2025-02-10T20:18:17.118000-08:00", "startTime": "2025-02-10T20:18:17.939000-08:00", "endTime": "2025-02-10T20:18:17.976000-08:00", "status": "SUCCEEDED", "command": "echo \"Hello World\"", "type": "SHELL", "exitCode": "0", "standardOutputContent": "Hello World\n", "logs": { "groupName": "group", "streamName": "stream", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } }], "commandExecutionsNotFound": [] } ``` ------ ### List command executions for a sandbox (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild list-command-executions-for-sandbox --sandbox-id $SANDBOX-ID --next-token $NEXT_TOKEN --max-results $MAX_RESULTS --sort-order $SORT_ORDER ``` + `--next-token` : The next token, if any, to get paginated results. You will get this value from previous execution of list sandboxes. + `--max-results` : (Optional) The maximum number of sandbox records to be retrieved. + `--sort-order` : The order in which sandbox records should be retrieved. ------ #### [ Sample request ] ``` aws codebuild list-command-executions-for-sandbox --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name" ``` ------ #### [ Sample response ] ``` { "commandExecutions": [{ "id": "aad6687e-07bc-45ab-a1fd-f5440229b528", "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05", "submitTime": "2025-02-10T20:18:35.304000-08:00", "startTime": "2025-02-10T20:18:35.615000-08:00", "endTime": "2025-02-10T20:18:35.651000-08:00", "status": "FAILED", "command": "fail command", "type": "SHELL", "exitCode": "127", "standardErrContent": "/codebuild/output/tmp/script.sh: 4: fail: not found\n", "logs": { "groupName": "group", "streamName": "stream", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } }, { "id": "c3c085ed-5a8f-4531-8e95-87d547f27ffd", "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05", "submitTime": "2025-02-10T20:18:17.118000-08:00", "startTime": "2025-02-10T20:18:17.939000-08:00", "endTime": "2025-02-10T20:18:17.976000-08:00", "status": "SUCCEEDED", "command": "echo \"Hello World\"", "type": "SHELL", "exitCode": "0", "standardOutputContent": "Hello World\n", "logs": { "groupName": "group", "streamName": "stream", "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream", "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2", "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream", "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz", "cloudWatchLogs": { "status": "ENABLED", "groupName": "group", "streamName": "stream" }, "s3Logs": { "status": "ENABLED", "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs", "encryptionDisabled": false } } } ] } ``` ------ ### List sandboxes (AWS CLI) ------ #### [ CLI command ] ``` aws codebuild list-sandboxes --next-token $NEXT_TOKEN --max-results $MAX_RESULTS --sort-order $SORT_ORDER ``` ------ #### [ Sample request ] ``` aws codebuild list-sandboxes ``` ------ #### [ Sample response ] ``` { "ids": [ "s3-log-project-integ-test-temp173925062814985d64e0f-7880-41df-9a3c-fb6597a266d2:827a5243-0841-4b69-a720-4438796f6967", "s3-log-project-integ-test-temp1739249999716bbd438dd-8bb8-47bd-ba6b-0133ac65b3d3:e2fa4eab-73af-42e3-8903-92fddaf9f378", "s3-log-project-integ-test-temp17392474779450fbdacc2-2d6e-4190-9ad5-28f891bb7415:cd71e456-2a4c-4db4-ada5-da892b0bba05", "s3-log-project-integ-test-temp17392246284164301421c-5030-4fa1-b4d3-ca15e44771c5:9e26ab3f-65e4-4896-a19c-56b1a95e630a", "s3-log-project-integ-test-temp173921367319497056d8d-6d8e-4f5a-a37c-a62f5686731f:22d91b06-df1e-4e9c-a664-c0abb8d5920b", "s3-log-project-integ-test-temp1739213439503f6283f19-390c-4dc8-95a9-c8480113384a:82cc413e-fc46-47ab-898f-ae23c83a613f", "s3-log-project-integ-test-temp1739054385570b1f1ddc2-0a23-4062-bd0c-24e9e4a99b99:c02562f3-2396-42ec-98da-38e3fe5da13a", "s3-log-project-integ-test-temp173905400540237dab1ac-1fde-4dfb-a8f5-c0114333dc89:d2f30493-f65e-4fa0-a7b6-08a5e77497b9", "s3-log-project-integ-test-temp17390534055719c534090-7bc4-48f1-92c5-34acaec5bf1e:df5f1c8a-f017-43b7-91ba-ad2619e2c059", "s3-log-project-integ-test-temp1739052719086a61813cc-ebb9-4db4-9391-7f43cc984ee4:d61917ec-8037-4647-8d52-060349272c4a", "s3-log-project-integ-test-temp173898670094078b67edb-c42f-42ed-9db2-4b5c1a5fc66a:ce33dfbc-beeb-4466-8c99-a3734a0392c7", "s3-log-project-integ-test-temp17389863425584d21b7cd-32e2-4f11-9175-72c89ecaffef:046dadf0-1f3a-4d51-a2c0-e88361924acf", "s3-log-project-integ-test-temp1738985884273977ccd23-394b-46cc-90d3-7ab94cf764dc:0370dc41-9339-4b0a-91ed-51929761b244", "s3-log-project-integ-test-temp1738985365972241b614f-8e41-4387-bd25-2b8351fbc9e0:076c392a-9630-47d8-85a9-116aa34edfff", "s3-log-project-integ-test-temp1738985043988a51a9e2b-09d6-4d24-9c3c-1e6e21ac9fa8:6ea3949c-435b-4177-aa4d-614d5956244c", "s3-log-project-integ-test-temp1738984123354c68b31ad-49d1-4f4b-981d-b66c00565ff6:6c3fff6c-815b-48b5-ada3-737400a6dee8", "s3-log-project-integ-test-temp1738977263715d4d5bf6c-370a-48bf-8ea6-905358a6cf92:968a0f54-724a-42d1-9207-6ed854b2fae8", "s3-log-project-integ-test-temp173897358796816ce8d7d-2a5e-41ef-855b-4a94a8d2795d:80f9a7ce-930a-402e-934e-d8b511d68b04", "s3-log-project-integ-test-temp17389730633301af5e452-0966-467c-b684-4e36d47f568c:cabbe989-2e8a-473c-af25-32edc8c28646", "s3-log-project-integ-test-temp1738901503813173fd468-b723-4d7b-9f9f-82e88d17f264:f7126a4a-b0d5-452f-814c-fea73718f805", "s3-log-project-integ-test-temp1738890502472c13616fb-bd0f-4253-86cc-28b74c97a0ba:c6f197e5-3a53-45b6-863e-0e6353375437", "s3-log-project-integ-test-temp17388903044683610daf3-8da7-43c6-8580-9978432432ce:d20aa317-8838-4966-bbfc-85b908213df1", "s3-log-project-integ-test-temp173888857196780b5ab8b-e54b-44fd-a222-c5a374fffe96:ab4b9970-ffae-47a0-b3a8-7b6790008cad", "s3-log-project-integ-test-temp1738888336931c11d378d-e74d-49a4-a723-3b92e6f7daac:4922f0e8-9b7d-4119-9c9f-115cd85e703e", "s3-log-project-integ-test-temp17388881717651612a397-c23f-4d88-ba87-2773cd3fc0c9:be91c3fc-418e-4feb-8a3a-ba58ff8f4e8a", "s3-log-project-integ-test-temp17388879727174c3c62ed-6195-4afb-8a03-59674d0e1187:a48826a8-3c0d-43c5-a1b5-1c98a0f978e9", "s3-log-project-integ-test-temp1738885948597cef305e4-b8b4-46b0-a65b-e2d0a7b83294:c050e77d-e3f8-4829-9a60-46149628fe96", "s3-log-project-integ-test-temp173888561463001a7d2a8-e4e4-4434-94db-09d3da9a9e17:8c3ac3f5-7111-4297-aec9-2470d3ead873", "s3-log-project-integ-test-temp1738869855076eb19cafd-04fe-41bd-8aa0-40826d0c0d27:d25be134-05cb-404a-85da-ac5f85d2d72c", "s3-project-integ-test-temp1738868157467148eacfc-d39b-49fc-a137-e55381cd2978:4909557b-c221-4814-b4b6-7d9e93d37c35", "s3-project-integ-test-temp1738820926895abec0af2-e33d-473c-9cf4-2122dd9d6876:8f5cf218-71d6-40a4-a4be-6cacebd7765f", "s3-project-integ-test-temp173881998877574f969a6-1c2e-4441-b463-ab175b45ce32:04396851-c901-4986-9117-585528e3877f", "s3-project-integ-test-temp17388189812309abd2604-29ba-4cf6-b6bf-073207b7db9c:540075c7-f5ec-41e8-9341-2233c09247eb", "s3-project-integ-test-temp1738818843474d3ea9ac1-b609-461b-bbdb-2da245c9bc96:865d4c3c-fbfe-4ece-9c92-d0c928341404", "s3-project-integ-test-temp1738818542236006e9169-e6d9-4344-9b59-f557e7aec619:1f9ffa87-da15-4290-83e2-eebdd877497b", "s3-project-integ-test-temp173881809557486ad11fd-7931-48d7-81d5-499cea52a6bc:c4c2efc4-685f-4e13-8b0f-1ef85ec300b1", "s3-project-integ-test-temp173881794103322941020-3f0b-49c3-b836-fcd818ec9484:0344cfba-de48-456d-b2a8-6566bd4a5d6e", "s3-project-integ-test-temp1738817680747b93d0d0b-ea16-497f-9559-af25ee6dcfdf:654a3a55-d92a-4dc6-8da8-56fd4d40d7e1", "s3-project-integ-test-temp17388174027191255c3da-086c-4270-b047-acac0b7bee0d:b7e82740-2c69-42fc-ab5a-dbf15bc016a1", "s3-project-integ-test-temp1738817099799016e7fa3-b9b5-46a2-bcd5-0888c646743f:8705a6a4-79ff-427a-a1c3-85c4e8fe462e", "s3-project-integ-test-temp1738816479281bb0c3606-5ebf-4623-bed5-12b60e9d3512:f23fc74b-a981-4835-8e28-375fcd4c99e4", "s3-project-integ-test-temp1738816263585c939a133-4d37-482c-9238-1dbff34b7674:ca28e234-0045-4ae6-8732-938b17597f50", "s3-project-integ-test-temp173881580873072d18733-8fe4-43b1-83f7-95f25bb27ccf:c6f0f55b-5736-47c7-a3aa-1b8461a6d5ed" ] } ``` ------ # Tutorial: Connecting to a sandbox using SSH This tutorial shows you how to connect to a CodeBuild sandbox using an SSH client. To complete this tutorial, you must first: + Ensure you have an existing AWS CodeBuild project. + Setup appropriate IAM permissions configured for your CodeBuild project role. + Install and configure AWS CLI on your local machine. ## Step 1: Start a sandbox **To start a CodeBuild sandbox in the console** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. Choose the build project, and then choose **Debug build**. ![\[The build project detail page in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/project-debug-build.png) 1. In the **SSH Client** tab and choose **Start sandbox**. ![\[The "SSH Client" tab in the console with "Start sandbox" button.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ssh-client-sandbox.png) 1. The sandbox initialization process may take some time. You can connect to the sandbox when its status changes to `RUN_SANDDBOX`. ![\[The SSH sandbox connection after the status changes to "RUN_SANDDBOX".\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/run-sandbox.png) ## Step 2: Modify local SSH configuration If you're connecting to sandbox for the first time, you need to perform a one-time setup process using the following steps: **To modify the local SSH configuration in the console** 1. Locate the setup commands for your operating system. 1. Open your local terminal, then copy and execute the provided commands to download and run the script to set up your local SSH configuration. For example, if your operating system is macOS, use the following command: ![\[The macOS commands for SSH connection to the CodeBuild sandbox in the console.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/modify-ssh-macOS.png) 1. The configuration script will add the required configurations for connecting to your sandboxes. You'll be prompted to accept these changes. 1. Upon successful configuration, a new SSH configuration entry for CodeBuild sandbox will be created. ![\[A successful SSH sandbox connection.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ssh-terminal-success.png) ## Step 3: Connect to the sandbox **To modify the local SSH configuration in the console** 1. Configure AWS CLI Authentication and ensure your AWS CLI user has the `codebuild:StartSandboxConnection` permission. For more information, see [ Authenticating using IAM user credentials for the AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-authentication-user.html) in the *AWS Command Line Interface User Guide for Version 1*. 1. Connect to your sandbox with following command: ``` ssh codebuild-sandbox-ssh=arn:aws:codebuild:us-east-1::sandbox/ ``` **Note** To troubleshoot connection failures, use the `-v` flag to enable verbose output. For example, `ssh -v codebuild-sandbox-ssh=arn:aws:codebuild:us-east-1::sandbox/`. For additional troubleshooting guidance, see [Troubleshooting AWS CodeBuild sandbox SSH connection issues](sandbox-troubleshooting.md). ## Step 4: Review your results Once connected, you can debug build failures, test build commands, experiment with configuration changes and verify environment variables and dependencies with your sandbox. # Troubleshooting AWS CodeBuild sandbox SSH connection issues Use the information in this topic to help you identify, diagnose, and address CodeBuild sandbox SSH connection issues. **Topics** + [`StartSandboxConnection` `InvalidInputException` error when SSH into CodeBuild sandbox environment](#sandbox-troubleshooting.invalid-input) + [Error: "Unable to locate credentials" when SSH into CodeBuild sandbox environment](#sandbox-troubleshooting.credentials) + [`StartSandboxConnection` `AccessDeniedException` error when SSH into CodeBuild sandbox environment](#sandbox-troubleshooting.access-denied) + [Error: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environment](#sandbox-troubleshooting.hostname) ## `StartSandboxConnection` `InvalidInputException` error when SSH into CodeBuild sandbox environment **Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`, you may encounter an `InvalidInputException` error such as: ``` An error occurred (InvalidInputException) when calling the StartSandboxConnection operation: Failed to start SSM session for {sandbox-arn} User: arn:aws:sts:::assumed-role//AWSCodeBuild- is not authorized to perform: ssm:StartSession on resource. ``` ``` An error occurred (InvalidInputException) when calling the StartSandboxConnection operation: Failed to start SSM session for sandbox : codebuild: is not connected. ``` **Possible cause:** + Missing Amazon EC2 Systems Manager Agent: The build image does not have the SSM agent properly installed or configured. + Insufficient Permissions: The CodeBuild project service role lacks the required SSM permissions. **Recommended solution:** If you are using a custom image for your build, do the following. 1. Install the SSM Agent. For more information, see [ Manually installing and uninstalling SSM Agent on Amazon EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-linux.html) in the **. The SSM Agent version must be `3.0.1295.0` or later. 1. Copy the file, [ https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/7.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/7.0/amazon-ssm-agent.json) to the `/etc/amazon/ssm/` directory in your image. This enables **Container Mode** in the SSM agent. 1. Ensure your CodeBuild project's service role has the following permissions, then restart the sandbox environment: ``` { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ssm:StartSession" ], "Resource": [ "arn:aws:codebuild:region:account-id:build/*", "arn:aws:ssm:region::document/AWS-StartSSHSession" ] } ``` ## Error: "Unable to locate credentials" when SSH into CodeBuild sandbox environment **Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`, you may encounter the following credentials error: ``` Unable to locate credentials. You can configure credentials by running "aws configure". ``` **Possible cause:** AWS credentials have not been properly configured in your local environment. **Recommended solution:** Configure your AWS CLI credentials by following the official documentation: [ Configuring settings for the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide for Version 2*. ## `StartSandboxConnection` `AccessDeniedException` error when SSH into CodeBuild sandbox environment **Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`, you may encounter the following permission error: ``` An error occurred (AccessDeniedException) when calling the StartSandboxConnection operation: User: arn:aws:sts::account-id:assumed-role/role-name is not authorized to perform: codebuild:StartSandboxConnection on resource: sandbox-arn because no identity-based policy allows the codebuild:StartSandboxConnection action ``` **Possible cause:** Your AWS credentials lack the necessary CodeBuild permissions to perform this operation. **Recommended solution:** Ensure that the IAM user or role associated with your AWS CLI credentials has the following permissions: ``` { "Effect": "Allow", "Action": [ "codebuild:StartSandboxConnection" ], "Resource": [ "arn:aws:codebuild:region:account-id:sandbox/*" ] } ``` ## Error: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environment **Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`, you encounter the following hostname resolution error: ``` ssh: Could not resolve hostname ``` **Possible cause:** This error typically occurs when the required CodeBuild sandbox connection script has not been properly executed in your local environment. **Recommended solution:** 1. Download the CodeBuild sandbox connection script. 1. Execute the script in your terminal to establish the necessary SSH configuration. 1. Retry your SSH connection to the sandbox environment. # Debug builds with Session Manager In AWS CodeBuild, you can pause a running build and then use AWS Systems Manager Session Manager to connect to the build container and view the state of the container. **Note** This feature is not available in Windows environments. **Topics** + [Prerequisites](#ssm.prerequisites) + [Pause the build](#ssm-pause-build) + [Start the build](#ssm-start-build) + [Connect to the build container](#ssm-connect) + [Resume the build](#ssm-resume-build) ## Prerequisites To allow Session Manager to be used with the build session, you must enable session connection for the build. There are two prerequisites: + CodeBuild Linux standard curated images already have the SSM agent installed and the SSM agent ContainerMode enabled. If you are using a custom image for your build, do the following: 1. Install the SSM Agent. For more information, see [Manually install SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) in the AWS Systems Manager User Guide. The SSM Agent version must be 3.0.1295.0 or later. 1. Copy the file [https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json) to the `/etc/amazon/ssm/` directory in your image. This enables Container Mode in the SSM agent. **Note** Custom images would require most updated SSM agent for this feature to work as expected. + The CodeBuild service role must have the following SSM policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" } ] } ``` ------ You can have the CodeBuild console automatically attach this policy to your service role when you start the build. Alternatively, you can attach this policy to your service role manually. + If you have **Auditing and logging session activity** enabled in Systems Manager preferences, the CodeBuild service role must also have additional permissions. The permissions are different, depending on where the logs are stored. CloudWatch Logs If using CloudWatch Logs to store your logs, add the following permission to the CodeBuild service role: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "logs:DescribeLogGroups", "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:*:*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:MyLogGroup:*" } ] } ``` Amazon S3 If using Amazon S3 to store your logs, add the following permission to the CodeBuild service role: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetEncryptionConfiguration", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ] } ] } ``` For more information, see [Auditing and logging session activity](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-logging-auditing.html) in the *AWS Systems Manager User Guide*. ## Pause the build To pause the build, insert the **codebuild-breakpoint** command in any of the build phases in your buildspec file. The build will be paused at this point, which allows you to connect to the build container and view the container in its current state. For example, add the following to the build phases in your buildspec file. ``` phases: pre_build: commands: - echo Entered the pre_build phase... - echo "Hello World" > /tmp/hello-world - codebuild-breakpoint ``` This code creates the `/tmp/hello-world` file and then pauses the build at this point. ## Start the build To allow Session Manager to be used with the build session, you must enable session connections for the build. To do this, when starting the build, follow these steps: 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. Choose the build project, and then choose **Start build with overrides**. 1. Choose **Advanced build overrides**. 1. In the **Environment** section, choose the **Enable session connection** option. If this option is not selected, all of the **codebuild-breakpoint** and **codebuild-resume** commands are ignored. 1. Make any other desired changes, and choose **Start build**. 1. Monitor the build status in the console. When the session is available, the **AWS Session Manager** link appears in the **Build status** section. ## Connect to the build container You can connect to the build container in one of two ways: CodeBuild console In a web browser, open the **AWS Session Manager** link to connect to the build container. A terminal session opens that allows you to browse and control the build container. AWS CLI Your local machine must have the Session Manager plugin installed for this procedure. For more information, see [Install the Session Manager Plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) in the AWS Systems Manager User Guide. 1. Call the **batch-get-builds** api with the build ID to get information about the build, including the session target identifier. The session target identifier property name varies depending on the output type of the `aws` command. This is why `--output json` is added to the command. ``` aws codebuild batch-get-builds --ids --region --output json ``` 1. Copy the `sessionTarget` property value. The `sessionTarget` property name can vary depending on the output type of the `aws` command. This is why `--output json` is added to the command in the previous step. 1. Use the following command to connect to the build container. ``` aws ssm start-session --target --region ``` For this example, verify that the `/tmp/hello-world` file exists and contains the text `Hello World`. ## Resume the build After you finish examining the build container, issue the **codebuild-resume** command from the container shell. ``` $ codebuild-resume ``` # Delete builds in AWS CodeBuild You can use the AWS CLI or the AWS SDKs to delete builds in AWS CodeBuild. **Topics** + [Delete builds (AWS CLI)](#delete-builds-cli) + [Delete builds (AWS SDKs)](#delete-builds-sdks) ## Delete builds (AWS CLI) Run the `batch-delete-builds` command: ``` aws codebuild batch-delete-builds --ids ids ``` In the preceding command, replace the following placeholder: + *ids*: Required string. The IDs of the builds to delete. To specify multiple builds, separate each build ID with a space. To get a list of build IDs, see the following topics: + [View a list of build IDs (AWS CLI)](view-build-list.md#view-build-list-cli) + [View a list of build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli) If successful, a `buildsDeleted` array appears in the output, containing the Amazon Resource Name (ARN) of each build that was successfully deleted. Information about builds that were not successfully deleted appears in output within a `buildsNotDeleted` array. For example, if you run this command: ``` aws codebuild batch-delete-builds --ids my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX ``` Information similar to the following appears in the output: ``` { "buildsNotDeleted": [ { "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", "statusCode": "BUILD_IN_PROGRESS" } ], "buildsDeleted": [ "arn:aws:codebuild:us-west-2:123456789012:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" ] } ``` ## Delete builds (AWS SDKs) For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Retry builds manually in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to manually retry either a single build or a batch build in AWS CodeBuild. **Topics** + [Retry a build manually (console)](#retry-build-console) + [Retry a build manually (AWS CLI)](#retry-build-cli) + [Retry a build manually (AWS SDKs)](#retry-build-sdks) ## Retry a build manually (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Do one of the following: + If the ***build-project-name*:*build-ID*** page is displayed, choose **Retry build**. + In the navigation pane, choose **Build history**. In the list of builds, select the box for the build, and then choose **Retry build**. + In the navigation pane, choose **Build projects**. In the list of build projects, in the **Name** column, choose the link for the build project's name. In the list of builds, select the box for the build, and then choose **Retry build**. **Note** By default, only the most recent 100 builds or build projects are displayed. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows. ## Retry a build manually (AWS CLI) + Run the **retry-build** command: ``` aws codebuild retry-build --id --idempotency-token ``` In the preceding command, replace the following placeholder: + **: Required string. The ID of the build or batch build to retry. To get a list of build IDs, see the following topics: + [View a list of build IDs (AWS CLI)](view-build-list.md#view-build-list-cli) + [View a list of batch build IDs (AWS CLI)](view-build-list.md#view-batch-build-list-cli) + [View a list of build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli) + [View a list of batch build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-batch-builds-for-project-cli) + `--idempotency-token`: Optional. If you run the **retry-build** command with the option, a unique case-sensitive identifier, or token, is included with the `retry-build` request. The token is valid for 5 minutes after the request. If you repeat the `retry-build` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error. ## Retry a build manually (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Retry builds automatically in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to automatically retry your builds in AWS CodeBuild. With auto-retry enabled, CodeBuild will automatically call `RetryBuild` using the project's service role after a failed build up to a specified limit. For example, if the auto-retry limit is set to two, CodeBuild will call the `RetryBuild` API to automatically retry your build for up to two additional times. **Note** CodeBuild does not support auto-retry for CodePipeline. **Topics** + [Retry a build automatically (console)](#auto-retry-build-console) + [Retry a build automatically (AWS CLI)](#auto-retry-build-cli) + [Automatically retry a build (AWS SDKs)](#auto-retry-build-sdks) ## Retry a build automatically (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Choose **Create project**. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). + In **Environment**: + For **Auto-retry limit**, enter the maximum number of auto-retries desired after a failed build. 1. In **Environment**, choose **Additional configuration**. 1. Continue with the default values and then choose **Create build project**. ## Retry a build automatically (AWS CLI) + Run the **create-project** command: ``` aws codebuild create-project \ --name "" \ --auto-retry-limit \ --source "" \ --artifacts {} \ --environment "{\"type\": \"environment-type>\",\"image\": \"image-type>\",\"computeType\": \"compute-type>\"}" \ --service-role "service-role>" ``` In the preceding command, replace the following placeholders: + **: Set the auto-retry limit to the maximum number of auto-retries desired after a failed build. + **, **, **, *environment-type>*, *image-type>*, *compute-type>*, and *service-role>*: Set your desired project configuration settings. ## Automatically retry a build (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Stop builds in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a build in AWS CodeBuild. **Topics** + [Stop a build (console)](#stop-build-console) + [Stop a build (AWS CLI)](#stop-build-cli) + [Stop a build (AWS SDKs)](#stop-build-sdks) ## Stop a build (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Do one of the following: + If the ***build-project-name*:*build-ID*** page is displayed, choose **Stop build**. + In the navigation pane, choose **Build history**. In the list of builds, select the box for the build, and then choose **Stop build**. + In the navigation pane, choose **Build projects**. In the list of build projects, in the **Name** column, choose the link for the build project's name. In the list of builds, select the box for the build, and then choose **Stop build**. **Note** By default, only the most recent 100 builds or build projects are displayed. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows. If AWS CodeBuild cannot successfully stop a build (for example, if the build process is already complete), the **Stop** button is disabled or might not appear. ## Stop a build (AWS CLI) + Run the **stop-build** command: ``` aws codebuild stop-build --id id ``` In the preceding command, replace the following placeholder: + *id*: Required string. The ID of the build to stop. To get a list of build IDs, see the following topics: + [View a list of build IDs (AWS CLI)](view-build-list.md#view-build-list-cli) + [View a list of build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli) If AWS CodeBuild successfully stops the build, the `buildStatus` value in the `build` object in the output is `STOPPED`. If CodeBuild cannot successfully stop the build (for example, if the build is already complete), the `buildStatus` value in the `build` object in the output is the final build status (for example, `SUCCEEDED`). ## Stop a build (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Stop batch builds in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a batch build in AWS CodeBuild. **Note** If you use Lambda compute in your batch build, the in-progress Lambda build cannot be stopped. **Topics** + [Stop a batch build (console)](#stop-batch-build-console) + [Stop a batch build (AWS CLI)](#stop-batch-build-cli) + [Stop a batch build (AWS SDKs)](#stop-batch-build-sdks) ## Stop a batch build (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Do one of the following: + If the ***build-project-name*:*build-ID*** page is displayed, choose **Stop build**. + In the navigation pane, choose **Build history**. In the list of builds, select the box for the build, and then choose **Stop build**. + In the navigation pane, choose **Build projects**. In the list of build projects, in the **Name** column, choose the link for the build project's name. In the list of builds, select the box for the build, and then choose **Stop build**. **Note** By default, only the most recent 100 builds or build projects are displayed. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows. ## Stop a batch build (AWS CLI) + Run the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html) command: ``` aws codebuild stop-build-batch --id ``` In the preceding command, replace the following placeholder: + **: Required string. The identifier of the batch build to stop. To get a list of batch build identifiers, see the following topics: + [View a list of batch build IDs (AWS CLI)](view-build-list.md#view-batch-build-list-cli) + [View a list of batch build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-batch-builds-for-project-cli) ## Stop a batch build (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Trigger AWS CodeBuild builds automatically You can create a trigger on a project to schedule a build once every hour, day, or week. You can also edit a trigger to use a custom rule with an Amazon CloudWatch cron expression. For example, using a cron expression, you can schedule a build at a specific time on every weekday. For information about creating and editing triggers, see [Create AWS CodeBuild triggers](#trigger-create) and [Edit AWS CodeBuild triggers](triggers-edit.md). **Topics** + [Create AWS CodeBuild triggers](#trigger-create) + [Edit AWS CodeBuild triggers](triggers-edit.md) ## Create AWS CodeBuild triggers You can create a trigger on a project to schedule a build once every hour, day, or week. You can also create a trigger using a custom rule with an Amazon CloudWatch cron expression. For example, using a cron expression, you can schedule a build at a specific time every weekday. **Note** It is not possible to start a batch build from a build trigger, an Amazon EventBridge event, or an AWS Step Functions task. **Topics** + [Create AWS CodeBuild triggers (console)](#trigger-create-console) + [Create AWS CodeBuild triggers programmatically](#trigger-create-code) ### Create AWS CodeBuild triggers (console) Use the following procedure to create triggers using the AWS Management Console. **To create a trigger** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. 1. Choose the link for the build project to which you want to add a trigger, and then choose the **Build triggers** tab. **Note** By default, the 100 most recent build projects are displayed. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows. 1. Choose **Create trigger**. 1. Enter a name in **Trigger name**. 1. From the **Frequency** drop-down list, choose the frequency for your trigger. If you want to create a frequency using a cron expression, choose **Custom**. 1. Specify the parameters for the frequency of your trigger. You can enter the first few characters of your selections in the text box to filter drop-down menu items. **Note** Start hours and minutes are zero-based. The start minute is a number between zero and 59. The start hour is a number between zero and 23. For example, a daily trigger that starts every day at 12:15 P.M. has a start hour of 12 and a start minute of 15. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero. A daily trigger that starts every day at 11:59 P.M. has a start hour of 23 and a start minute of 59. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-triggers.html) 1. Select **Enable this trigger**. 1. (Optional) Expand **Advanced section**. In **Source version**, type a version of your source. + For Amazon S3, enter the version ID that corresponds to the version of the input artifact you want to build. If **Source version** is left blank, the latest version is used. + For AWS CodeCommit, type a commit ID. If **Source version** is left blank, the default branch's HEAD commit ID is used. + For GitHub or GitHub Enterprise, type a commit ID, a pull request ID, a branch name, or a tag name that corresponds to the version of the source code you want to build. If you specify a pull request ID, it must use the format `pr/pull-request-ID` (for example, `pr/25`). If you specify a branch name, the branch's HEAD commit ID is used. If **Source version** is blank, the default branch's HEAD commit ID is used. + For Bitbucket, type a commit ID, a branch name, or a tag name that corresponds to the version of the source code you want to build. If you specify a branch name, the branch's HEAD commit ID is used. If **Source version** is blank, the default branch's HEAD commit ID is used. 1. (Optional) Specify a timeout between 5 minutes and 2160 minutes (36 hours). This value specifies how long AWS CodeBuild attempts a build before it stops. If **Hours** and **Minutes** are left blank, the default timeout value specified in the project is used. 1. Choose **Create trigger**. ### Create AWS CodeBuild triggers programmatically CodeBuild uses Amazon EventBridge rules for build triggers. You can use the EventBridge API to programmatically create build triggers for your CodeBuild projects. See [Amazon EventBridge API Reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/) for more information. # Edit AWS CodeBuild triggers You can edit a trigger on a project to schedule a build once every hour, day, or week. You can also edit a trigger to use a custom rule with an Amazon CloudWatch cron expression. For example, using a cron expression, you can schedule a build at a specific time on every weekday. For information about creating a trigger, see [Create AWS CodeBuild triggers](build-triggers.md#trigger-create). **Topics** + [Edit AWS CodeBuild triggers (console)](#triggers-edit-console) + [Edit AWS CodeBuild triggers programmatically](#trigger-edit-code) ## Edit AWS CodeBuild triggers (console) Use the following procedure to edit triggers using the AWS Management Console. **To edit a trigger** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build projects**. 1. Choose the link for the build project you want to change, and then choose the **Build triggers** tab. **Note** By default, the 100 most recent build projects are displayed. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows. 1. Choose the radio button next to the trigger you want to change, and then choose **Edit**. 1. From the **Frequency** drop-down list, choose the frequency for your trigger. If you want to create a frequency using a cron expression, choose **Custom**. 1. Specify the parameters for the frequency of your trigger. You can enter the first few characters of your selections in the text box to filter drop-down menu items. **Note** Start hours and minutes are zero-based. The start minute is a number between zero and 59. The start hour is a number between zero and 23. For example, a daily trigger that starts every day at 12:15 P.M. has a start hour of 12 and a start minute of 15. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero. A daily trigger that starts every day at 11:59 P.M. has a start hour of 23 and a start minute of 59. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/triggers-edit.html) 1. Select **Enable this trigger**. **Note** You can use the Amazon CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) to edit source version, timeout, and other options that are not available in AWS CodeBuild. ## Edit AWS CodeBuild triggers programmatically CodeBuild uses Amazon EventBridge rules for build triggers. You can use the EventBridge API to programmatically edit the build triggers for your CodeBuild projects. See [Amazon EventBridge API Reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/) for more information. # View build details in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view details about builds managed by CodeBuild. **Topics** + [View build details (console)](#view-build-details-console) + [View build details (AWS CLI)](#view-build-details-cli) + [View build details (AWS SDKs)](#view-build-details-sdks) + [Build phase transitions](view-build-details-phases.md) ## View build details (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Do one of the following: + In the navigation pane, choose **Build history**. In the list of builds, in the **Build run** column, choose the link for the build. + In the navigation pane, choose **Build projects**. In the list of build projects, in the **Name** column, choose the link for the name of the build project. Then, in the list of builds, in the **Build run** column, choose the link for the build. **Note** By default, only the 10 most recent builds or build projects are displayed. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows. ## View build details (AWS CLI) For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md). Run the **batch-get-builds** command: ``` aws codebuild batch-get-builds --ids ids ``` Replace the following placeholder: + *ids*: Required string. One or more build IDs to view details about. To specify more than one build ID, separate each build ID with a space. You can specify up to 100 build IDs. To get a list of build IDs, see the following topics: + [View a list of build IDs (AWS CLI)](view-build-list.md#view-build-list-cli) + [View a list of build IDs for a build project (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli) For example, if you run this command: ``` aws codebuild batch-get-builds --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE my-other-project:813bb6c6-891b-426a-9dd7-6d8a3EXAMPLE ``` If the command is successful, data similar to that described in [To view summarized build information](getting-started-overview.md#getting-started-cli-monitor-build-cli) appears in the output. ## View build details (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # Build phase transitions Builds in AWS CodeBuild proceed in phases: ![\[The CodeBuild phases.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/build-phases.png) **Important** The `UPLOAD_ARTIFACTS` phase is always attempted, even if the `BUILD` phase fails. # View a list of build IDs in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for builds managed by CodeBuild. **Topics** + [View a list of build IDs (console)](#view-build-list-console) + [View a list of build IDs (AWS CLI)](#view-build-list-cli) + [View a list of batch build IDs (AWS CLI)](#view-batch-build-list-cli) + [View a list of build IDs (AWS SDKs)](#view-build-list-sdks) ## View a list of build IDs (console) 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. In the navigation pane, choose **Build history**. **Note** By default, only the 10 most recent builds are displayed. To view more builds, choose the gear icon, and then choose a different value for **Builds per page** or use the back and forward arrows. ## View a list of build IDs (AWS CLI) For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md). + Run the **list-builds** command: ``` aws codebuild list-builds --sort-order sort-order --next-token next-token ``` In the preceding command, replace the following placeholders: + *sort-order*: Optional string used to indicate how to list the build IDs. Valid values include `ASCENDING` and `DESCENDING`. + *next-token*: Optional string. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*. To get the next batch of items in the list, run this command again, adding the next token to the call. To get all of the items in the list, keep running this command with each subsequent next token, until no more next tokens are returned. For example, if you run this command: ``` aws codebuild list-builds --sort-order ASCENDING ``` A result similar to the following might appear in the output: ``` { "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", "ids": [ "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE" "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE" ] } ``` If you run this command again: ``` aws codebuild list-builds --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== ``` A result similar to the following might appear in the output: ``` { "ids": [ "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE", "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE", ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE" ] } ``` ## View a list of batch build IDs (AWS CLI) For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md). + Run the **list-build-batches** command: ``` aws codebuild list-build-batches --sort-order sort-order --next-token next-token ``` In the preceding command, replace the following placeholders: + *sort-order*: Optional string used to indicate how to list the batch build IDs. Valid values include `ASCENDING` and `DESCENDING`. + *next-token*: Optional string. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*. To get the next batch of items in the list, run this command again, adding the next token to the call. To get all of the items in the list, keep running this command with each subsequent next token, until no more next tokens are returned. For example, if you run this command: ``` aws codebuild list-build-batches --sort-order ASCENDING ``` A result similar to the following might appear in the output: ``` { "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", "ids": [ "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE" "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE" ] } ``` If you run this command again: ``` aws codebuild list-build-batches --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== ``` A result similar to the following might appear in the output: ``` { "ids": [ "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE", "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE", ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE" ] } ``` ## View a list of build IDs (AWS SDKs) For more information about using CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md). # View a list of build IDs for a build project in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for a build project in CodeBuild. **Topics** + [View a list of build IDs for a build project (console)](#view-builds-for-project-console) + [View a list of build IDs for a build project (AWS CLI)](#view-builds-for-project-cli) + [View a list of batch build IDs for a build project (AWS CLI)](#view-batch-builds-for-project-cli) + [View a list of build IDs for a build project (AWS SDKs)](#view-builds-for-project-sdks) ## View a list of build IDs for a build project (console) 1. Open the CodeBuild console at [https://console.aws.amazon.com/codebuild/](https://console.aws.amazon.com/codebuild/). 1. In the navigation pane, choose **Build projects**. In the list of build projects, in the **Name** column, choose the build project. **Note** By default, only the most recent 100 builds or build projects are displayed. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows. ## View a list of build IDs for a build project (AWS CLI) For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md). Run the **list-builds-for-project** command, as follows: ``` aws codebuild list-builds-for-project --project-name project-name --sort-order sort-order --next-token next-token ``` In the preceding command, replace the following placeholders: + *project-name*: Required string used to indicate the name of the build project to list builds IDs for. To get a list of build projects, see [View a list of build project names (AWS CLI)](view-project-list.md#view-project-list-cli). + *sort-order*: Optional string used to indicate how to list the build IDs. Valid values include `ASCENDING` and `DESCENDING`. + *next-token*: Optional string. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*. To get the next batch of items in the list, run this command again, adding the next token to the call. To get all of the items in the list, keep running this command with each subsequent next token that is returned, until no more next tokens are returned. For example, if you run this command similar to this: ``` aws codebuild list-builds-for-project --project-name codebuild-demo-project --sort-order ASCENDING ``` A result like the following might appear in the output: ``` { "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", "ids": [ "codebuild-demo-project:9b175d16-66fd-4e71-93a0-50a08EXAMPLE" "codebuild-demo-project:a9d1bd09-18a2-456b-8a36-7d65aEXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:fe70d102-c04f-421a-9cfa-2dc15EXAMPLE" ] } ``` If you run this command again: ``` aws codebuild list-builds-for-project --project-name codebuild-demo-project --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== ``` You might see a result like the following in the output: ``` { "ids": [ "codebuild-demo-project:98253670-7a8a-4546-b908-dc890EXAMPLE" "codebuild-demo-project:ad5405b2-1ab3-44df-ae2d-fba84EXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:f721a282-380f-4b08-850a-e0ac1EXAMPLE" ] } ``` ## View a list of batch build IDs for a build project (AWS CLI) For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md). Run the **list-build-batches-for-project** command, as follows: ``` aws codebuild list-build-batches-for-project --project-name project-name --sort-order sort-order --next-token next-token ``` In the preceding command, replace the following placeholders: + *project-name*: Required string used to indicate the name of the build project to list builds IDs for. To get a list of build projects, see [View a list of build project names (AWS CLI)](view-project-list.md#view-project-list-cli). + *sort-order*: Optional string used to indicate how to list the build IDs. Valid values include `ASCENDING` and `DESCENDING`. + *next-token*: Optional string. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*. To get the next batch of items in the list, run this command again, adding the next token to the call. To get all of the items in the list, keep running this command with each subsequent next token that is returned, until no more next tokens are returned. For example, if you run this command similar to this: ``` aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING ``` A result like the following might appear in the output: ``` { "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", "ids": [ "codebuild-demo-project:9b175d16-66fd-4e71-93a0-50a08EXAMPLE" "codebuild-demo-project:a9d1bd09-18a2-456b-8a36-7d65aEXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:fe70d102-c04f-421a-9cfa-2dc15EXAMPLE" ] } ``` If you run this command again: ``` aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== ``` You might see a result like the following in the output: ``` { "ids": [ "codebuild-demo-project:98253670-7a8a-4546-b908-dc890EXAMPLE" "codebuild-demo-project:ad5405b2-1ab3-44df-ae2d-fba84EXAMPLE" ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:f721a282-380f-4b08-850a-e0ac1EXAMPLE" ] } ``` ## View a list of build IDs for a build project (AWS SDKs) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md).