Menu
AWS CodeBuild
User Guide (API Version 2016-10-06)

Run a Build in AWS CodeBuild

You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in AWS CodeBuild.

Run a Build (Console)

To use AWS CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in Use AWS CodePipeline with AWS CodeBuild.

  1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codebuild/.

  2. Do one of the following:

    • If you just finished creating a build project, the Build project: project-name page should be displayed. Choose Start build.

    • If you created a build project earlier, in the navigation pane, choose Build projects. Choose the build project, and then choose Start build.

  3. On the Start new build page, do one of the following:

    • For Amazon S3, for the optional Source version value, type 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 will be used.

    • For AWS CodeCommit, for the optional Source version value, for Branch, choose the name of the branch that contains the version of the source code you want to build. For Source version, accept the displayed HEAD commit ID or type a different one. If Source version is blank, the default branch's HEAD commit ID is used. You cannot type a tag name for Source version. To specify a tag, type the tag's commit ID.

    • For GitHub, for the optional Source version value, 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 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 Source version is blank, the default branch's HEAD commit ID is used.

    • For Bitbucket, for the optional Source version value, 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 a branch name is specified, the branch's HEAD commit ID is used. If Source version is blank, the default branch's HEAD commit ID is used.

  4. Expand Show advanced options.

    • If you want to change the output artifacts type for this build only, choose the replacement type in Artifacts type.

    • If you want to change the name of the output artifact for this build only, type the replacement name in Artifacts name.

    • If you want to change the name of the output bucket for this build only, choose the replacement name in Bucket name.

    • If you want to change the way output artifacts are packaged for this build only, choose the replacement packaging type in Artifacts packaging.

    • If you want to change the build timeout for this build only, specify the new value in Timeout.

  5. Expand Environment variables.

    If you want to change the environment variables for this build only, change the values for Name, Value, and Type. Use Add row to add a new environment variable for this build only. Choose the delete (X) button next to an environment variable you do not want to use in this build.

    Others can see an environment variable by using the AWS CodeBuild console and the AWS CLI. If you have no concerns about the visibility of your environment variable, set the Name and Value fields, and then set Type to Plaintext.

    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. For Type, choose Parameter Store. For Name, type an identifier for AWS CodeBuild to reference. For Value, type the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store. Using a parameter named /CodeBuild/dockerLoginPassword as an example, for Type, choose Parameter Store. For Name, type LOGIN_PASSWORD. For Value, type /CodeBuild/dockerLoginPassword.

    Important

    We recommend that you store parameters in Amazon EC2 Systems Manager Parameter Store with parameter names that start with /CodeBuild/ (for example, /CodeBuild/dockerLoginPassword). You can use the AWS CodeBuild console to create a parameter in Amazon EC2 Systems Manager. Choose Create a parameter, and then follow the instructions in the dialog box. (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 AWS CodeBuild console to create a parameter, the console starts the parameter with /CodeBuild/ as it is being stored. For more information, see Systems Manager Parameter Store and Systems Manager Parameter Store Console Walkthrough 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 service role in your account earlier, then AWS 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.

    If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with /CodeBuild/, and you chose Create a service role in your account, then you must update that service role to allow access to parameter names that do not start with /CodeBuild/. This is because that service role allows access only to parameter names that start with /CodeBuild/.

    Any environment variables you set replace existing environment variables. For example, if the Docker image already contains an environment variable named MY_VAR with a value 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, its value is determined as follows:

    • The value in the start build operation call takes highest precedence.

    • The value in the build project definition takes next precedence.

    • The value in the build spec declaration takes lowest precedence.

  6. Choose Start build.

    For detailed information about this build, see View Build Details (Console).

Run a Build (AWS CLI)

Note

To use AWS CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in Create a Pipeline that Uses AWS CodeBuild (AWS CLI).

For more information about using the AWS CLI with AWS CodeBuild, see the Command Line Reference.

  1. Run the start-build command in one of the following ways:

    Copy
    aws codebuild start-build --project-name 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.

    Copy
    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, build spec, or default build timeout period.

  2. If you run the start-build command with the --project-name option, replace project-name 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 a List of Build Project Names.

  3. 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:

    Copy
    { "projectName": "projectName", "sourceVersion": "sourceVersion", "artifactsOverride": { "type": "type", "location": "location", "path": "path", "namespaceType": "namespaceType", "name": "artifactsOverride-name", "packaging": "packaging" }, "environmentVariablesOverride": [ { "name": "environmentVariablesOverride-name", "value": "value", "type": "environmentVariablesOverride-type" } ], "buildspecOverride": "buildspecOverride", "timeoutInMinutesOverride": timeoutInMinutesOverride }

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

    • type: Optional string. The build output artifact type that overrides for this build the one defined in the build project.

    • location: Optional string. The build output artifact location that overrides for this build the one defined in the build project.

    • path: Optional string. The build output artifact path that overrides for this build the one defined in the build project.

    • namespaceType: Optional string. The build output artifact path type that overrides for this build the one defined in the build project.

    • name: Optional string. The build output artifact name that overrides for this build the one defined in the build project.

    • packaging: Optional string. The build output artifact packaging type that overrides for this build the one defined in the build project.

    • environmentVariablesOverride-name: Optional string. The name of an environment variable in the build project whose value you want to override for this build.

    • value: Optional string. The value of the environment variable defined in the build project that you want to override for this build.

    • environmentVariablesOverride-type: Optional string. The type of environment variable in the build project whose value you want to override for this build.

      Important

      We recommend 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. AWS 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 AWS CodeBuild console to create a parameter in Amazon EC2 Systems Manager. Choose Create a parameter, and then follow the instructions in the dialog box. (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 AWS 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 Systems Manager Parameter Store and Systems Manager Parameter Store Console Walkthrough 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 AWS 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 build spec declaration takes lowest precedence.

    • buildspecOverride: Optional string. A build spec declaration that overrides for this build the one defined in the build project. If this value is set, it can be either an inline build spec definition or the path to an alternate build spec file relative to the value of the built-in CODEBUILD_SRC_DIR environment variable.

    • timeoutInMinutesOverride: Optional number. The number of build timeout minutes that overrides for this build the one defined in the build project.

    For information about valid values for these placeholders, see Create a Build Project (AWS CLI). To get a list of the latest settings for a build project, see View a Build Project's Details.

  4. Switch to the directory that contains the file you just saved, and run the start-build command again.

    Copy
    aws codebuild start-build --cli-input-json file://start-build.json
  5. If successful, data similar to that described in the To run the build (AWS 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).

Start Running Builds Automatically (AWS CLI)

If your source code is stored in a GitHub 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:

Copy
aws codebuild create-webhook --project-name
  • where project-name is the name of the build project that contains the source code to be rebuilt.

If this command is successful, information similar to the following appears in the output:

Copy
{ "webhook": { "url": "url" } }
  • where url is the URL to the GitHub webhook.

Stop Running Builds Automatically (AWS CLI)

If your source code is stored in a GitHub repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the respository. For more information, see Start Running Builds Automatically (AWS CLI).

If you have enabled this behavior, you can turn it off by running the delete-webhook command as follows:

Copy
aws codebuild delete-webhook --project-name
  • where project-name 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.

Run a Build (AWS SDKs)

To use AWS CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in Use AWS CodePipeline with AWS CodeBuild to Test Code and Run Builds instead.

For information about using AWS CodeBuild with the AWS SDKs, see the AWS SDKs and Tools Reference.