# 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).