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

Build Environment Reference for AWS CodeBuild

When you call AWS CodeBuild to run a build, you must provide information about the build environment AWS CodeBuild will use. A build environment represents a combination of operating system, programming language runtime, and tools that AWS CodeBuild uses to run a build. For information about how a build environment works, see How AWS CodeBuild Works.

A build environment contains a Docker image. For information, see "Docker images" in Understanding the architecture on the Docker Docs website.

When you provide information to AWS CodeBuild about the build environment, you specify the identifier of a Docker image in a supported repository type. These include the AWS CodeBuild Docker image repository, publicly available images in Docker Hub, and Amazon EC2 Container Registry (Amazon ECR) repositories in your AWS account:

  • We recommend that you use Docker images stored in the AWS CodeBuild Docker image repository, because they are optimized for use with the service. For more information, see Docker Images Provided by AWS CodeBuild.

  • To get the identifier of a publicly available Docker image stored in Docker Hub, see Searching for images on the Docker Docs website.

  • To learn how to work with Docker images stored in Amazon ECR repositories in your AWS account, see our Amazon ECR Sample.

In addition to a Docker image identifier, you also specify a set of computing resources that the build environment will use. For more information, see Build Environment Compute Types.

Docker Images Provided by AWS CodeBuild

AWS CodeBuild manages the following Docker images:

Platform Programming language or framework Runtime version Additional components Image identifier Definition
Amazon Linux 2016.03, 64-bit v2.3.2 Golang 1.6 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-go-1.6-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Golang 1.5.3 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-go-1.5-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Golang 1.5.3 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-go-1.5-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.4.3 Java 1.8.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-8-amazonlinux-64:2.4.3
Amazon Linux 2016.03, 64-bit v2.1.6 Java 1.8.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-8-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Java 1.8.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-8-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.4.3 Java 1.7.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-7-amazonlinux-64:2.4.3
Amazon Linux 2016.03, 64-bit v2.1.6 Java 1.7.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-7-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Java 1.7.0 Apache Maven 3.3.3, Apache Ant 1.9.6, Gradle 2.7 aws/codebuild/eb-java-7-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v4.0.0 Node.js 6.10.0 Git 2.7.4, npm 2.15.5 aws/codebuild/eb-nodejs-6.10.0-amazonlinux-64:4.0.0
Amazon Linux 2016.03, 64-bit v2.1.3 Node.js 4.4.6 Git 2.7.4, npm 2.15.5 aws/codebuild/eb-nodejs-4.4.6-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.1.6 Python 3.4.3 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-3.4-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Python 3.4.3 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-3.4-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Python 3.4 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-3.4-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Python 2.7.10 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.7-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Python 2.7.10 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.7-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Python 2.7 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.7-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Python 2.6.9 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.6-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Python 2.6.9 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.6-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Python 2.6 meld3 1.0.2, pip 7.1.2, setuptools 18.4 aws/codebuild/eb-python-2.6-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Ruby 2.3.1 Bundler, RubyGems aws/codebuild/eb-ruby-2.3-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Ruby 2.3.1 Bundler, RubyGems aws/codebuild/eb-ruby-2.3-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Ruby 2.3 Bundler, RubyGems aws/codebuild/eb-ruby-2.3-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Ruby 2.2.5 Bundler, RubyGems aws/codebuild/eb-ruby-2.2-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Ruby 2.2.5 Bundler, RubyGems aws/codebuild/eb-ruby-2.2-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Ruby 2.2 Bundler, RubyGems aws/codebuild/eb-ruby-2.2-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Ruby 2.1.9 Bundler, RubyGems aws/codebuild/eb-ruby-2.1-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Ruby 2.1.9 Bundler, RubyGems aws/codebuild/eb-ruby-2.1-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Ruby 2.1 Bundler, RubyGems aws/codebuild/eb-ruby-2.1-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.3.2 Ruby 2.0 Bundler, RubyGems aws/codebuild/eb-ruby-2.0-amazonlinux-64:2.3.2
Amazon Linux 2016.03, 64-bit v2.1.6 Ruby 2.0.0 Bundler, RubyGems aws/codebuild/eb-ruby-2.0-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Ruby 2.0.0 Bundler, RubyGems aws/codebuild/eb-ruby-2.0-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.1.6 Ruby 1.9.3 Bundler, RubyGems aws/codebuild/eb-ruby-1.9-amazonlinux-64:2.1.6
Amazon Linux 2016.03, 64-bit v2.1.3 Ruby 1.9.3 Bundler, RubyGems aws/codebuild/eb-ruby-1.9-amazonlinux-64:2.1.3
Amazon Linux 2016.03, 64-bit v2.3.2 Ruby 1.9 Bundler, RubyGems aws/codebuild/eb-ruby-1.9-amazonlinux-64:2.3.2
Ubuntu 14.04 (Base image) AWS CLI, Git 1.9.1 aws/codebuild/ubuntu-base:14.04 ubuntu/ubuntu-base/14.04
Ubuntu 14.04 Android 24.4.1 AWS CLI, Git 1.9.1, Java 8, pip 8.1.2, Python 2.7 aws/codebuild/android-java-8:24.4.1 ubuntu/android-java-8/24.4.1
Ubuntu 14.04 Android 24.4.1 AWS CLI, Git 1.9.1, Java 7, pip 8.1.2, Python 2.7 aws/codebuild/android-java-7:24.4.1 ubuntu/android-java-7/24.4.1
Ubuntu 14.04 Android 24.4.1 AWS CLI, Git 1.9.1, Java 6, pip 8.1.2, Python 2.7 aws/codebuild/android-java-6:24.4.1 ubuntu/android-java-6/24.4.1
Ubuntu 14.04 Docker 1.12.1 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/docker:1.12.1 ubuntu/docker/1.12.1
Ubuntu 14.04 Golang 1.7.3 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/golang:1.7.3 ubuntu/golang/1.7.3
Ubuntu 14.04 Golang 1.6.3 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/golang:1.6.3 ubuntu/golang/1.6.3
Ubuntu 14.04 Golang 1.5.4 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/golang:1.5.4 ubuntu/golang/1.5.4
Ubuntu 14.04 Java 8 Apache Ant 1.9.6, Apache Maven 3.3.3, AWS CLI, Git 1.9.1, Gradle 2.7, pip 8.1.2, Python 2.7 aws/codebuild/java:openjdk-8 ubuntu/java/openjdk-8
Ubuntu 14.04 Java 7 Apache Ant 1.9.6, Apache Maven 3.3.3, AWS CLI, Git 1.9.1, Gradle 2.7, pip 8.1.2, Python 2.7 aws/codebuild/java:openjdk-7 ubuntu/java/openjdk-7
Ubuntu 14.04 Java 6 Apache Ant 1.9.6, Apache Maven 3.2.5, AWS CLI, Git 1.9.1, Gradle 2.7, pip 8.1.2, Python 2.7 aws/codebuild/java:openjdk-6 ubuntu/java/openjdk-6
Ubuntu 14.04 Node.js 7.0.0 AWS CLI, Git 1.9.1, NPM, pip 8.1.2, Python 2.7 aws/codebuild/nodejs:7.0.0 ubuntu/nodejs/7.0.0
Ubuntu 14.04 Node.js 6.3.1 AWS CLI, Git 1.9.1, NPM, pip 8.1.2, Python 2.7 aws/codebuild/nodejs:6.3.1 ubuntu/nodejs/6.3.1
Ubuntu 14.04 Node.js 5.12.0 AWS CLI, Git 1.9.1, NPM, pip 8.1.2, Python 2.7 aws/codebuild/nodejs:5.12.0 ubuntu/nodejs/5.12.0
Ubuntu 14.04 Node.js 4.4.7 AWS CLI, Git 1.9.1, NPM, pip 8.1.2, Python 2.7 aws/codebuild/nodejs:4.4.7 ubuntu/nodejs/4.4.7
Ubuntu 14.04 Node.js 4.3.2 AWS CLI, Git 1.9.1, NPM, pip 8.1.2, Python 2.7 aws/codebuild/nodejs:4.3.2 ubuntu/nodejs/4.3.2
Ubuntu 14.04 Python 3.5.2 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/python:3.5.2 ubuntu/python/3.5.2
Ubuntu 14.04 Python 3.4.5 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/python:3.4.5 ubuntu/python/3.4.5
Ubuntu 14.04 Python 3.3.6 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/python:3.3.6 ubuntu/python/3.3.6
Ubuntu 14.04 Python 2.7.12 AWS CLI, Git 1.9.1, pip 8.1.2, Python 2.7 aws/codebuild/python:2.7.12 ubuntu/python/2.7.12
Ubuntu 14.04 Ruby 2.3.1 AWS CLI, Bundler 1.13.5, Git 1.9.1, pip 8.1.2, Python 2.7, RubyGems 2.6.7 aws/codebuild/ruby:2.3.1 ubuntu/ruby/2.3.1
Ubuntu 14.04 Ruby 2.2.5 AWS CLI, Bundler 1.13.5, Git 1.9.1, pip 8.1.2, Python 2.7, RubyGems 2.6.7 aws/codebuild/ruby:2.2.5 ubuntu/ruby/2.2.5
Ubuntu 14.04 Ruby 2.1.10 AWS CLI, Bundler 1.13.5, Git 1.9.1, pip 8.1.2, Python 2.7, RubyGems 2.6.7 aws/codebuild/ruby:2.1.10 ubuntu/ruby/2.1.10
Ubuntu 14.04 .NET Core 1.1 aws/codebuild/dot-net:core-1

You can use a build specification to install other components (for example, the AWS CLI, Apache Maven, Apache Ant, Mocha, RSpec, or similar) during the install build phase. For more information, see Build Spec Example.

AWS CodeBuild frequently updates the list of Docker images. To get the most current list, do one of the following:

  • In the AWS CodeBuild console, in the Create project wizard or Update project page, for Environment image, choose Use an image managed by AWS CodeBuild. Choose from the Operating system, Runtime, and Version drop-down lists. For more information, see Create a Build Project (Console) or Change a Build Project's Settings (Console).

  • In the AWS CodePipeline console, in the Create pipeline wizard on the Step 3: Build page, or in the AWS CodeBuild section of the Add action or Edit action pane, choose Create a new build project. In Environment: How to build, for Environment image, choose Use an image managed by AWS CodeBuild. Choose from the Operating system, Runtime, and Version drop-down lists. For more information, see Create a Pipeline that Uses AWS CodeBuild (AWS CodePipeline Console) or Add an AWS CodeBuild Build Action to a Pipeline (AWS CodePipeline Console).

  • For the AWS CLI, run the list-curated-environment-images command:

    Copy
    aws codebuild list-curated-environment-images
  • For the AWS SDKs, call the ListCuratedEnvironmentImages operation for your target programming language. For more information, see the AWS SDKs and Tools Reference.

  • For AWS CodeBuild HTTP API, call the ListCuratedEnvironmentImages operation:

    Sample headers:

    Copy
    POST / HTTP/1.1 Host: codebuild.us-east-2.amazonaws.com Accept-Encoding: identity Content-Length: 2 X-Amz-Target: CodeBuild_20161006.ListCuratedEnvironmentImages 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
    {}

For more information about the Docker images that contain eb- in their identifer, see Supported Platforms and Platform History in the AWS Elastic Beanstalk Developer Guide. Docker images that contain eb- in their identifer are not available in the AWS CodeBuild and AWS CodePipeline consoles.

To confirm the version of a component installed on a Docker image, you can run a command during a build. The version number for the component will appear in the output. For example, include one or more of the following commands in your build specification:

  • For Apache Ant, run ant -version.

  • For Apache Maven, run mvn -version.

  • For the AWS CLI, run aws --version.

  • For Bundler, run bundle version.

  • For Git, run git --version.

  • For Gradle, run gradle --version.

  • For Java, run java -version.

  • For NPM, run npm --version.

  • For pip, run pip --version.

  • For Python, run python --version.

  • For RubyGems, run gem --version.

  • For setuptools, run easy_install --version.

The following build command (entered through the AWS CodeBuild or AWS CodePipeline console as part of a build project's settings) returns the versions of the AWS CLI, Git, pip, and Python on a Docker image that has these components installed: aws --version && git --version && pip --version && python --version.

Build Environment Compute Types

AWS CodeBuild provides build environments with the following available memory, vCPUs, and available disk space:

Compute type computeType value Memory vCPUs Disk space
build.general1.small BUILD_GENERAL1_SMALL 3 GB 2 64 GB
build.general1.medium BUILD_GENERAL1_MEDIUM 7 GB 4 128 GB
build.general1.large BUILD_GENERAL1_LARGE 15 GB 8 128 GB

Note

For custom build environment images, AWS CodeBuild supports Docker images up to 10 GB uncompressed, regardless of the compute type. To check your build image's size, use Docker to run the docker images REPOSITORY:TAG command.

To choose one of these compute types:

Shells and Commands in Build Environments

You provide a set of commands for AWS CodeBuild to run in a build environment during the lifecycle of a build (for example, installing build dependencies and testing and compiling your source code). There are several ways to specify these commands:

  • Create a build spec file and include it with your source code. In this file, specify the commands you want to run in each phase of the build lifecycle. For more information, see the Build Specification Reference for AWS CodeBuild.

  • Use the AWS CodeBuild or AWS CodePipeline console to create a build project. In Insert build commands, for Build command, specify the commands you want to run in the build phase. For more information, see the description of Insert build commands in Create a Build Project (Console) or Use AWS CodePipeline with AWS CodeBuild.

  • Use the AWS CodeBuild console to change the settings of a build project. In Insert build commands, for Build command, specify the commands you want to run in the build phase. For more information, see the description of Insert build commands in Change a Build Project's Settings (Console).

  • Use the AWS CLI, AWS SDKs, or the AWS CodeBuild HTTP API to create a build project or change the settings of a build project. Reference the source code that contains a build spec file with your commands, or specify a single string that includes the contents of an equivalent build spec file. For more information, see the description for the buildspec value in Create a Build Project or Change a Build Project's Settings.

  • Use the AWS CLI, AWS SDKs, or the AWS CodeBuild HTTP API to start a build, specifying a build spec file or a single string that includes the contents of an equivalent build spec file. For more information, see the description for the buildspecOverride value in Run a Build.

You can specify any command that is supported by the build environment's default shell. (If you want to know the default shell, you can run a command such as echo $SHELL during a build.) In build spec version 0.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment. This means that each command runs in isolation from all other commands. Therefore, by default, you cannot run a single command that relies on the state of any previous commands (for example, changing directories or setting environment variables). To get around this limitation, we recommend you use version 0.2, which solves this issue. If you must use version 0.1 for some reason, we recommend the following approaches:

  • Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell. For example, you could include a file named my-script.sh in your source code that contains commands such as cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;. Then, in your build spec file, specify the command ./my-script.sh.

  • In your build spec file, or for the console's Build command setting for the build phase only, specify a single command that includes all of the commands you want to run in a single instance of the default shell (for example, cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd).

If AWS CodeBuild encounters an error, the error might be more difficult to troubleshoot compared to running a single command in its own instance of the default shell.

Environment Variables in Build Environments

AWS CodeBuild provides several environment variables that you can use in your build commands:

  • AWS_DEFAULT_REGION: The AWS region where the build is running (for example, us-east-1). This environment variable is used primarily by the AWS CLI.

  • AWS_REGION: The AWS region where the build is running (for example, us-east-1). This environment variable is used primarily by the AWS SDKs.

  • CODEBUILD_BUILD_ARN: The Amazon Resource Name (ARN) of the build (for example, arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE).

  • CODEBUILD_BUILD_ID: The AWS CodeBuild ID of the build (for example, codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE).

  • CODEBUILD_BUILD_IMAGE: The AWS CodeBuild build image identifier (for example, aws/codebuild/java:openjdk-8).

  • CODEBUILD_BUILD_SUCCEEDING: Whether the current build is succeeding. Set to 0 if the build is failing, or 1 if the build is succeeding.

  • CODEBUILD_INITIATOR: The entity that started the build. If AWS CodePipeline started the build, this is the pipeline's name, for example codepipeline/my-demo-pipeline. If an IAM user started the build, this is the user's name, for example MyUserName. If the Jenkins plugin for AWS CodeBuild started the build, this is the string CodeBuild-Jenkins-Plugin.

  • CODEBUILD_KMS_KEY_ID: The identifier of the AWS KMS key that AWS CodeBuild is using to encrypt the build output artifact (for example, arn:aws:kms:region-ID:account-ID:key/key-ID or alias/key-alias).

  • CODEBUILD_RESOLVED_SOURCE_VERSION: For builds run by AWS CodePipeline, the commit ID or Amazon S3 version ID of the source code to be built. Note that this value is available only if the pipeline's related Source action is based on an Amazon S3, AWS CodeCommit, or GitHub repository.

  • CODEBUILD_SOURCE_REPO_URL: The URL to the input artifact or source code repository. For Amazon S3, this is s3:// followed by the bucket name and path to the input artifact. For AWS CodeCommit and GitHub, this is the repository's clone URL.

  • CODEBUILD_SOURCE_VERSION: For Amazon S3, the version ID associated with the input artifact. For AWS CodeCommit, the commit ID or branch name associated with the version of the source code to be built. For GitHub, the commit ID, branch name, or tag name associated with the version of the source code to be built.

  • CODEBUILD_SRC_DIR: The directory path that AWS CodeBuild uses for the build (for example, /tmp/src123456789/src).

  • HOME: This environment variable is always set to /root.

You can also provide build environments with your own environment variables. For more information, see the following topics:

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.

For sensitive values, we recommend you store them in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your build spec. To store sensitive values, see Systems Manager Parameter Store and Systems Manager Parameter Store Console Walkthrough in the Amazon EC2 Systems Manager User Guide. To retrieve them, see the parameter-store mapping in Build Spec Syntax.

To list all of the available environment variables in a build environment, you can run the printenv command during a build. With the exception of those previously listed, environment variables that start with CODEBUILD_ are for AWS CodeBuild internal use. They should not be used in your build commands.

Background Tasks in Build Environments

You can run background tasks in build environments. To do this, in your build spec, use the nohup command to run a command as a task in the background, even if the build process exits the shell. Use the disown command to forcibly stop a running background task.