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, or AWS SDKs 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 AWS CodeBuild to be able to access. After you choose Authorize application, back in the AWS CodeBuild console, for Repository, choose the name of the repository that contains the source code.

    • If you chose Bitbucket, follow the instructions to connect (or reconnect) with Bitbucket. On the Bitbucket Confirm access to your account page, for Organization access, choose Grant access. After you choose Grant access, 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 build commands different from 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 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 might want to do this if you're 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, and then do the following:

      • If you want to use your project name for the build output ZIP file or folder, leave Artifacts name blank. Otherwise, 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 earlier 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 service 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 service 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 is updated to work with the other build project. A service role can work with up to 10 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 is not 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 stops the build if it is not complete. If hours and minutes are left blank, the default value of 60 minutes is 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 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 provided by AWS CodeBuild with Docker support. Otherwise, all associated builds that attempt to interact with the Docker daemon fail. You must also start the Docker daemon so that your builds can interact with it. 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 these 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, value, and type of each environment variable for builds to use. Use Add row to add an environment variable.

    Others can see environment variables 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 name 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 to 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/.

    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 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 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 appears 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. 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", "type": "environmentVariable-type" } ], "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, BITBUCKET, 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 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 create a build project. When you use the console to connect (or reconnect) with GitHub, on the GitHub Authorize application page, for Organization access, choose Request access next to each repository you want AWS CodeBuild to be able to access. Choose Authorize application. (After you have connected to your GitHub account, you do not need to finish creating the build project. You can close the AWS CodeBuild console.) To instruct AWS CodeBuild to use this connection, in the source object, set the auth object's type value to OAUTH.

        • For Bitbucket, 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 Bitbucket account. To do this, use the AWS CodeBuild console to create a build project. When you use the console to connect (or reconnect) with Bitbucket, on the Bitbucket Confirm access to your account page, choose Grant access. (After you have connected to your Bitbucket account, you do not need to finish creating the build project. You can close the AWS CodeBuild console.) To instruct AWS CodeBuild to 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 is 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 CODEBUILD_SRC_DIR environment variable. 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 uses 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 uses 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 project's 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 used by this build environment. 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 used by this build environment. 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, value, and type of environmentVariable-name, environmentVariable-value, and environmentVariable-type.

        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 environmentVariable-name and environmentVariable-value, and then set environmentVariable-type to PLAINTEXT.

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

        Important

        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 to 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, 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 provided by AWS CodeBuild with Docker support. Otherwise, all associated builds that attempt to interact with the Docker daemon fail. You must also start the Docker daemon so that your builds can interact with it. 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 these 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 uses 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 stops the build if it is not complete. If not specified, the default of 60 is 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 uses 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 is 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).

  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 appears 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", "type": "environmentVariable-type" } ] }, "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 information about using AWS CodeBuild with the AWS SDKs, see the AWS SDKs and Tools Reference.