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

Create a Build Project in AWS CodeBuild

You can use the AWS CodeBuild console, AWS CLI, AWS SDKs, or AWS CodeBuild HTTP API to create a build project.

Prerequisites

Answer the questions in Plan a Build.

Create a Build Project (Console)

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

  2. If a welcome page is displayed, choose Get started.

    If a welcome page is not displayed, on the navigation pane, choose Build projects, and then choose Create project.

  3. On the Configure your project page, for Project name, type a name for this build project. Build project names must be unique across each AWS account.

  4. (Optional) Choose Add description, and type a description in the Description box.

  5. In Source: What to build, for Source provider, choose the source code provider type, and then do one of the following:

    • If you chose Amazon S3, then for Bucket, choose the name of the input bucket that contains the source code. For S3 object key, type the name of the ZIP file that contains the source code.

    • If you chose AWS CodeCommit, then for Repository, choose the name of the repository.

    • If you chose GitHub, follow the instructions to connect (or reconnect) with GitHub. On the GitHub Authorize application page, for Organization access, choose Request access next to each repository you want to allow AWS CodeBuild to have access to. After you choose Authorize application, back in the AWS CodeBuild console, for Repository, choose the name of the repository that contains the source code.

  6. In Environment: How to build, for Environment image, do one of the following:

    • To use a Docker image managed by AWS CodeBuild, choose Use an image managed by AWS CodeBuild, and then make selections from Operating system, Runtime, and Version.

    • To use another Docker image, choose Specify a Docker image. For Custom image type, choose Other or Amazon ECR. If you choose Other, then for Custom image ID, type the name and tag of the Docker image in Docker Hub, using the format repository-name/image-name:image-tag. If you choose Amazon ECR, then use Amazon ECR repository and Amazon ECR image to choose the Docker image in your AWS account.

  7. Do one of the following:

    • If your source code includes a build spec file, choose Use the buildspec.yml in the source code root directory.

    • If your source code does not include a build spec file, or if you want to run a different set of build commands than the ones specified for the build phase in the buildspec.yml file in the source code's root directory, choose Insert build commands. For Build command, type the commands you want to run in the build phase. For multiple commands, separate each command by &&, for example mvn test && mvn package. To run commands in other phases, or if you have a particularly long list of commands for the build phase, add a buildspec.yml file to the source code root directory, add the commands to the file, and then choose Use the buildspec.yml in the source code root directory.

    For more information, see the Build Spec Reference.

  8. In Artifacts: Where to put the artifacts from this build project, for Artifacts type, do one of the following:

    • If you do not want to create any build output artifacts, choose No artifacts. You may want to do this, for example, if you only running build tests or you want to push a Docker image to an Amazon ECR repository.

    • To store the build output in an Amazon S3 bucket, choose Amazon S3. Then do the following:

      • Leave Artifacts name blank if you want to use your project name for the build output ZIP file or folder. Otherwise, to specify a name for the build output ZIP file or folder, type the name in the Artifacts name box. (If you want to output a ZIP file, and you want the ZIP file to have a file extension, be sure to include it after the ZIP file name.)

      • For Bucket name, choose the name of the output bucket.

      • If you chose Insert build commands previously in this procedure, then for Output files, type the locations of the files from the build that you want to put into the build output ZIP file or folder. For multiple locations, separate each location with a comma, for example appspec.yml, target/my-app.jar. For more information, see the description of files in Build Spec Syntax.

  9. In Service role, do one of the following:

    • If you do not have an AWS CodeBuild service role, choose Create a new role in your account. In Role name, accept the default name or type your own. Service role names must be unique across your AWS account.

    • If you have an AWS CodeBuild service role, choose Choose an existing role from your account. In Role name, choose the service role.

    Note

    When you use the console to create or update a build project, you can create an AWS CodeBuild service role at the same time. By default, the role works with that build project only. If you use the console to associate this service role with another build project, the role will be updated to work with the other build project. A service role can work with up to ten build projects.

  10. Expand Show advanced settings.

    Note

    If you arrived at this page by choosing Get started from a welcome page, then the Show advanced settings section will not be displayed. Skip to step 18 of this procedure. For information about changing default settings, see Change a Build Project's Settings (Console).

  11. (Optional) For Timeout, specify a value between 5 minutes and 480 minutes (8 hours) after which AWS CodeBuild will stop the build if it is not complete. If hours and minutes are left blank, the default value of 60 minutes will be used.

  12. (Optional) For Encryption key, do one of the following:

    • To use the AWS-managed customer master key (CMK) for Amazon S3 in your account to encrypt the build output artifacts, leave Encryption key blank. This is the default.

    • To use a customer-managed CMK to encrypt the build output artifacts, in Encryption key, type the ARN of the customer-managed CMK. Use the format arn:aws:kms:region-ID:account-ID:key/key-ID.

  13. (Optional) Select the Privileged check box only if you plan to use this build project to build Docker images, and the build environment image you chose is not one provided by AWS CodeBuild with Docker support. Otherwise, all associated builds that attempt to interact with the Docker daemon will fail. Note that you must also start the Docker daemon so that your builds can interact with it as needed. One way to do this is to initialize the Docker daemon in the install phase of your build spec by running the following build commands. (Do not run the following build commands if you chose a build environment image provided by AWS CodeBuild with Docker support.)

    Copy
    - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://0.0.0.0:2375 --storage-driver=overlay& - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"
  14. (Optional) If you chose Amazon S3 for Artifacts type earlier in this procedure, then for Artifacts packaging, do one of the following:

    • To have AWS CodeBuild create a ZIP file containing the build output, choose Zip.

    • To have AWS CodeBuild create a folder containing the build output, choose None. (This is the default.)

  15. For Compute type, choose one of the available options.

  16. (Optional) For Environment variables, type the name and value of environment variables for builds to use. Use Add row to add an environment variable.

    Important

    We strongly discourage using environment variables to store sensitive values, especially AWS access key IDs and secret access keys. Environment variables can be displayed in plain text using tools such as the AWS CodeBuild console and the AWS CLI.

    To store and retrieve sensitive values, we recommend your build commands use the AWS CLI to interact with the Amazon EC2 Systems Manager Parameter Store. The AWS CLI comes preinstalled and preconfigured on all build environments provided by AWS CodeBuild. For more information, see Systems Manager Parameter Store and Systems Manager Parameter Store CLI Walkthrough in the Amazon EC2 Systems Manager User Guide

    Any environment variables you set will 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 will be 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 will be 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 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.

  17. (Optional) For Tags, type the name and value of any tags you want supporting AWS services to use. Use Add row to add a tag. You can add up to 50 tags.

  18. Choose Continue.

  19. On the Review page, do one of the following:

    • To run a build, choose Save and build.

    • To finish creating the build project without running a build, choose Save.

Create a Build Project (AWS CLI)

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

  1. Run the create-project command:

    Copy
    aws codebuild create-project --generate-cli-skeleton

    JSON-formatted data will appear in the output. Copy the data to a file (for example, create-project.json) in a location on the local computer or instance where the AWS CLI is installed. Then modify the copied data as follows, and save your results:

    Copy
    { "name": "project-name", "description": "description", "source": { "type": "source-type", "location": "source-location", "buildspec": "buildspec", "auth": { "type": "auth-type", "resource": "resource" } }, "artifacts": { "type": "artifacts-type", "location": "artifacts-location", "path": "path", "namespaceType": "namespaceType", "name": "artifacts-name", "packaging": "packaging" }, "environment": { "type": "environment-type", "image": "image", "computeType": "computeType", "environmentVariables": [ { "name": "environmentVariable-name", "value": "environmentVariable-value" } ], "privilegedMode": privilegedMode }, "serviceRole": "serviceRole", "timeoutInMinutes": timeoutInMinutes, "encryptionKey": "encryptionKey", "tags": [ { "key": "tag-key", "value": "tag-value" } ] }

    Replace the following:

    • project-name: Required value. The name for this build project. This name must be unique across all of the build projects in your AWS account.

    • description: Optional value. The description for this build project.

    • For the required source object, information about this build project's source code settings. These settings include the following:

      • source-type: Required value. The type of repository that contains the source code to build. Valid values include CODECOMMIT, CODEPIPELINE, GITHUB, and S3.

      • source-location: Required value (unless you set source-type to CODEPIPELINE). The location of the source code for the specified repository type:

        • For AWS CodeCommit, the HTTPS clone URL to the repository that contains the source code and the build spec (for example, https://git-codecommit.region-id.amazonaws.com/v1/repos/repo-name).

        • For Amazon S3, the build input bucket name, followed by a forward slash (/), followed by the name of the ZIP file that contains the source code and the build spec (for example, bucket-name/object-name.zip). This assumes that the ZIP file is in the root of the build input bucket. (If the ZIP file is in a folder inside of the bucket, use for example bucket-name/path/to/object-name.zip instead.)

        • For GitHub, the HTTPS clone URL to the repository that contains the source code and the build spec. Also, you must connect your AWS account to your GitHub account. To do this, use the AWS CodeBuild console to begin creating a build project. When you use the console to connect (or reconnect) with GitHub, on the GitHub Authorize application page that displays, for Organization access, choose Request access next to each repository you want to allow AWS CodeBuild to have access to. Then choose Authorize application. (After you have connected to your GitHub account, you do not need to finish creating the build project, and you may then leave the AWS CodeBuild console.) To instruct AWS CodeBuild to then use this connection, in the source object, set the auth object's type value to OAUTH.

        • For AWS CodePipeline, do not specify a location value for source. It will be ignored by AWS CodePipeline because when you create a pipeline in AWS CodePipeline, you specify the source code location in the Source stage of the pipeline.

      • buildspec: Optional value. The build specification definition or file to use. 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 environment variable CODEBUILD_SRC_DIR. If this value is not provided or is set to an empty string, then the source code must contain a buildspec.yml file in its root directory. For more information, see Build Spec File Name and Storage Location.

      • auth: This object is used only by the AWS CodeBuild console. Do not specify values for auth-type (unless source-type is set to GITHUB, as described previously) or resource.

    • For the required artifacts object, information about this build project's output artifact settings. These settings include the following:

      • artifacts-type: Required value. The type of build output artifact. Valid values include CODEPIPELINE, NO_ARTIFACTS, and S3.

      • artifacts-location: Required value (unless you set artifacts-type to CODEPIPELINE or NO_ARTIFACTS). The location of the build output artifact:

        • If you specified CODEPIPELINE for artifacts-type, do not specify a location for artifacts.

        • If you specified NO_ARTIFACTS for artifacts-type, do not specify a location for artifacts.

        • If you specified S3 for artifacts-type, then this is name of the output bucket you created or identified in the prerequisites.

      • path: Optional value. The path and name of the build output ZIP file or folder:

        • If you specified CODEPIPELINE for artifacts-type, then do not specify a path for artifacts.

        • If you specified NO_ARTIFACTS for artifacts-type, do not specify a path for artifacts.

        • If you specified S3 for artifacts-type, then this is the path inside of artifacts-location to the build output ZIP file or folder. If you do not specify a value for path, then AWS CodeBuild will use namespaceType (if specified) and artifacts-name to determine the path and name of the build output ZIP file or folder. For example, if you specify MyPath for path and MyArtifact.zip for artifacts-name, then the path and name would be MyPath/MyArtifact.zip.

      • namespaceType: Optional value. The path and name of the build output ZIP file or folder:

        • If you specified CODEPIPELINE for artifacts-type, do not specify a namespaceType for artifacts.

        • If you specified NO_ARTIFACTS for artifacts-type, do not specify a namespaceType for artifacts.

        • If you specified S3 for artifacts-type, valid values include BUILD_ID and NONE. Use BUILD_ID to insert the build ID into the path of the build output ZIP file or folder. Otherwise, use NONE. If you do not specify a value for namespaceType, AWS CodeBuild will use path (if specified) and artifacts-name to determine the path and name of the build output ZIP file or folder. For example, if you specify MyPath for path, BUILD_ID for namespaceType, and MyArtifact.zip for artifacts-name, then the path and name would be MyPath/build-ID/MyArtifact.zip.

      • artifacts-name: Required value (unless you set artifacts-type to CODEPIPELINE or NO_ARTIFACTS). The path and name of the build output ZIP file or folder:

        • If you specified CODEPIPELINE for artifacts-type, do not specify a name for artifacts.

        • If you specified NO_ARTIFACTS for artifacts-type, do not specify a name for artifacts.

        • If you specified S3 for artifacts-type, then this is the name of the build output ZIP file or folder inside of artifacts-location. For example, if you specify MyPath for path and MyArtifact.zip for artifacts-name, then the path and name would be MyPath/MyArtifact.zip.

      • packaging: Optional value. The type of build output artifact to create:

        • If you specified CODEPIPELINE for artifacts-type, do not specify a packaging for artifacts.

        • If you specified NO_ARTIFACTS for artifacts-type, do not specify a packaging for artifacts.

        • If you specified S3 for artifacts-type, valid values include ZIP and NONE. To create a ZIP file that contains the build output, use ZIP. To create a folder that contains the build output, use NONE. The default value is NONE.

    • For the required environment object, information about this build project's participating build environment settings. These settings include:

      • environment-type: Required value. The type of build environment. The only allowed value is LINUX_CONTAINER.

      • image: Required value. The Docker image identifier this build environment will use. Typically, this identifier is expressed as image-name:tag. For example, in the Docker repository that AWS CodeBuild uses to manage its Docker images, this could be aws/codebuild/java:openjdk-8. In Docker Hub, maven:3.3.9-jdk-8. In Amazon ECR, account-id.dkr.ecr.region-id.amazonaws.com/your-Amazon-ECR-repo-name:tag.

      • computeType: Required value. A category corresponding to the number of CPU cores and memory this build environment will use. Allowed values include BUILD_GENERAL1_SMALL, BUILD_GENERAL1_MEDIUM, and BUILD_GENERAL1_LARGE.

      • For the optional environmentVariables array, information about any environment variables you want to specify for this build environment. Each environment variable is expressed as an object containing a name and value value of environmentVariable-name and environmentVariable-value.

        Important

        We strongly discourage using environment variables to store sensitive values, especially AWS access key IDs and secret access keys. Environment variables can be displayed in plain text using tools such as the AWS CodeBuild console and the AWS CLI.

        To store and retrieve sensitive values, we recommend your build commands use the AWS CLI to interact with the Amazon EC2 Systems Manager Parameter Store. The AWS CLI comes preinstalled and preconfigured on all build environments provided by AWS CodeBuild. For more information, see Systems Manager Parameter Store and Systems Manager Parameter Store CLI Walkthrough in the Amazon EC2 Systems Manager User Guide

        Any environment variables you set will 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 will be 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 will be 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 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.

      • You must specify privilegedMode with a value of true only if you plan to use this build project to build Docker images, and the build environment image you specified is not one provided by AWS CodeBuild with Docker support. Otherwise, all associated builds that attempt to interact with the Docker daemon will fail. Note that you must also start the Docker daemon so that your builds can interact with it as needed. One way to do this is to initialize the Docker daemon in the install phase of your build spec by running the following build commands. (Do not run the following build commands if you specified a build environment image provided by AWS CodeBuild with Docker support.)

        Copy
        - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://0.0.0.0:2375 --storage-driver=overlay& - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"
    • serviceRole: Required value. The ARN of the service role AWS CodeBuild will use to interact with services on behalf of the IAM user (for example, arn:aws:iam::account-id:role/role-name).

    • timeoutInMinutes: Optional value. The number of minutes, between 5 to 480 (8 hours), after which AWS CodeBuild will stop the build if it is not complete. If not specified, the default of 60 will be used. To determine if and when AWS CodeBuild stopped a build due to a timeout, run the batch-get-builds command. To determine if the build has stopped, look in the output for a buildStatus value of FAILED. To determine when the build timed out, look in the output for the endTime value associated with a phaseStatus value of TIMED_OUT.

    • encryptionKey: Optional value. The alias or ARN of the AWS KMS customer master key (CMK) AWS CodeBuild will use to encrypt the build output. If you specify an alias, use the format arn:aws:kms:region-ID:account-ID:key/key-ID or, if an alias exists, use the format alias/key-alias. If not specified, the AWS-managed CMK for Amazon S3 will be used.

    • For the optional tags array, information about any tags you want to associate with this build project. You can specify up to 50 tags. These tags can be used by any AWS service that supports AWS CodeBuild build project tags. Each tag is expressed as an object containing a key and value value of tag-key and tag-value.

    For an example, see To create the build project (AWS CLI) in Getting Started.

  2. Switch to the directory that contains the file you just saved, and run the create-project command again:

    Copy
    aws codebuild create-project --cli-input-json file://create-project.json
  3. If successful, data similar to the following will appear in the output:

    Copy
    { "project": { "name": "project-name", "description": "description", "serviceRole": "serviceRole", "tags": [ { "key": "tags-key", "value": "tags-value" } ], "artifacts": { "namespaceType": "namespaceType", "packaging": "packaging", "path": "path", "type": "artifacts-type", "location": "artifacts-location", "name": "artifacts-name" }, "lastModified": lastModified, "timeoutInMinutes": timeoutInMinutes, "created": created, "environment": { "computeType": "computeType", "image": "image", "type": "environment-type", "environmentVariables": [ { "name": "environmentVariable-name", "value": "environmentVariable-value" } ] }, "source": { "type": "source-type", "location": "source-location", "buildspec": "buildspec", "auth": { "type": "auth-type", "resource": "resource" } }, "encryptionKey": "encryptionKey", "arn": "arn" } }
    • The project object contains information about the new build project:

      • The lastModified value represents the time, in Unix time format, when information about the build project was last changed.

      • The created value represents the time, in Unix time format, when the build project was created.

      • The arn value represents the ARN of the build project.

Note

Except for the build project name, you can change any of the build project's settings later. For more information, see Change a Build Project's Settings (AWS CLI).

To start running a build, see Run a Build (AWS CLI).

Create a Build Project (AWS SDKs)

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

Create a Build Project (HTTP API)

For more information about using the AWS CodeBuild HTTP API, see the HTTP API Reference.

Call the CreateProject operation:

Sample headers:

Copy
POST / HTTP/1.1 Host: codebuild.us-east-2.amazonaws.com Accept-Encoding: identity Content-Length: 581 X-Amz-Target: CodeBuild_20161006.CreateProject X-Amz-Date: 20161006T213734Z User-Agent: aws-cli/1.10.3 Python/2.7.9 Windows/8 botocore/1.3.25 Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIAJTTFEXAMPLE/20161003/us-east-2/codebuild/aws4_request, SignedHeaders=content-type;host;user-agent;x-amz-date;x-amz-target, Signature=bc48f52bEXAMPLE

Sample request body:

Copy
{ "name": "sample-ant-helloworld-project", "source": { "type": "S3", "location": "codebuild-region-ID-account-ID-input-bucket/AntHelloWorldWithTestsSample.zip" }, "artifacts": { "type": "S3", "location": "codebuild-region-ID-account-ID-output-bucket", "name": "AntHelloWorldWithTestsOutputArtifact.zip", "packaging": "ZIP" }, "environment": { "type": "LINUX_CONTAINER", "image": "ant-image-ID", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "arn:aws:iam::account-ID:role/CodeBuildServiceRole", "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" }

If successful, a response is returned with body content similar to the following:

Copy
{ "project": { "name": "sample-ant-helloworld-project", "serviceRole": "arn:aws:iam::account-ID:role/CodeBuildServiceRole", "tags": [], "artifacts": { "packaging": "ZIP", "type": "S3", "location": "codebuild-region-ID-account-ID-output-bucket", "name": "sample-ant-helloworld-project" }, "lastModified": 1475530648.823, "timeoutInMinutes": 60, "created": 1475530648.823, "environment": { "computeType": "BUILD_GENERAL1_SMALL", "image": "ant-image-ID", "type": "LINUX_CONTAINER", "environmentVariables": [] }, "source": { "type": "S3", "location": "codebuild-region-ID-account-ID-input-bucket/AntHelloWorldWithTestsSample.zip" }, "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID", "arn": "arn:aws:codebuild:region-ID:account-ID:project/sample-ant-helloworld-project" } }

For descriptions of request and response data, see Create a Build Project (AWS CLI).