Run a build (Amazon CLI)

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

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.

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.

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.

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.

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 Amazon 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:

We recommend that you store an environment variable with a sensitive value, such as an Amazon access key ID, an Amazon 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 Amazon 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 Amazon Systems Manager parameter store and Walkthrough: Create and test a String parameter (console) 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:

For information about valid values for these placeholders, see Create a build project (Amazon CLI). For a list of the latest settings for a build project, see View a build project's details.

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

If successful, data similar to that described in the To run the build procedure appears in the output.