The procedures in this guide support the new console design. If you choose to use
the older version of the console, you will find
many of the concepts and basic procedures in this guide still apply. To access help
in the new console, choose the information icon.

Getting Started with CodeBuild

In this walkthrough, you use AWS CodeBuild to build a collection of sample source
code input files (called build input artifacts or
build input) into a deployable version of the source code (called build output artifact or build
output). Specifically, you instruct CodeBuild to use Apache Maven, a common build tool,
to build a set of Java class files into a Java Archive
(JAR) file. You do not need to be familiar with Apache Maven or Java to complete this
walkthrough.

Step 1: Create or Use Amazon S3 Buckets to
Store the Build Input and Output

To complete this walkthrough, you need two Amazon S3 buckets:

One of these buckets stores the build input (the input bucket). In this walkthrough, we name this input bucket
codebuild-region-ID-account-ID-input-bucket, where
region-ID represents the AWS Region of the bucket, and account-ID represents your AWS
account ID.

The other bucket stores the build output (the output bucket). In this walkthrough, we name this output bucket
codebuild-region-ID-account-ID-output-bucket.

If you chose a different name for either of these buckets, be sure to use it throughout
this walkthrough.

These two buckets must be in the same AWS Region as your builds. For example, if you
instruct CodeBuild to run a build in the US East (Ohio)
Region, then these buckets must also be in the US East (Ohio) Region.

To create a bucket, see Creating a
Bucket in the Amazon Simple Storage Service User Guide.

Note

You can use a single bucket for this walkthrough, but using two buckets makes it easier
to see where the build input is coming from and where
the build output is going.

Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket
repositories, this walkthrough does not show you how to use them. For more
information, see Plan a Build.

Step 2: Create the Source Code to
Build

In this step, you create the source code that you want CodeBuild to build to the output
bucket. This source code consists of two Java class files and
an Apache Maven Project Object Model (POM) file.

In an empty directory on your local computer or instance, create this
directory structure.

(root directory name)
`-- src
|-- main
| `-- java
`-- test
`-- java

Using a text editor of your choice, create this file, name it
MessageUtil.java, and then save it in the
src/main/java directory.

This class file creates as output the string of characters passed into it. The
MessageUtil constructor sets the string of characters. The
printMessage method creates the output. The
salutationMessage method outputs Hi! followed by
the string of characters.

Create this file, name it TestMessageUtil.java, and then save it
in the /src/test/java directory.

This class file sets the message variable in the
MessageUtil class to Robert. It then tests to see
if the message variable was successfully set by checking whether
the strings Robert and Hi!Robert appear in the
output.

Create this file, name it pom.xml, and then save it in
the root (top level) directory.

Step 3: Create the Build
Spec

In this step, you create a build specification (build spec) file. A build spec is a collection of build commands and related settings, in YAML format, that CodeBuild
uses to run a build. Without a build spec, CodeBuild cannot successfully convert
your build input into build output or locate the build output artifact in the build
environment to upload to your output bucket.

Create this file, name it buildspec.yml, and then save it in
the root (top level) directory.

Because a build spec declaration must be valid YAML, the spacing in a build spec
declaration is important. If the number of spaces in your build spec declaration
does not match this one, the build might fail immediately. You can use a YAML
validator to test whether your build spec declaration is valid YAML.

Note

Instead of including a build spec file in your source code, you can declare build
commands separately when you create a build project. This is helpful if you want to
build your source code with different build commands without updating your source
code's repository each time. For more information, see Build Spec Syntax.

In this build spec declaration:

version represents the version of the build spec standard being
used. This build spec declaration uses the latest version,
0.2.

phases represents the build phases during which you can instruct CodeBuild to run commands.
These build phases are listed here as
install, pre_build, build, and post_build. You cannot change the spelling of these build phase
names, and you cannot create more build phase names.

In this example, during the build phase, CodeBuild runs the mvn install command. This command instructs Apache Maven
to compile, test, and package the compiled Java class files into a build output artifact.
For completeness, a few echo commands are
placed in each build phase in this example. When you view detailed build information
later in this walkthrough, the output of these echo
commands can help you better understand how CodeBuild runs commands and in which order.
(Although all build phases are included in this example, you are
not required to include a build phase if you do not plan to run any commands during
that phase.) For each build phase, CodeBuild runs each specified
command, one at a time, in the order listed, from beginning to end.

artifacts represents the set of build output artifacts that CodeBuild uploads to the output
bucket. files represents
the files to include in the build output. CodeBuild uploads the single messageUtil-1.0.jar file found in the target
relative directory in the build environment. The file name messageUtil-1.0.jar and the directory name target are
based on the way Apache Maven creates and stores build output artifacts for this example
only. In your own builds, these file names and directories
are different.

Do not include the (root directory name) directory, only the directories and files in the
(root directory name) directory.

Upload the MessageUtil.zip file to the input bucket named
codebuild-region-ID-account-ID-input-bucket.

Important

For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store
a
build spec file named buildspec.yml in the root (top level) of
each repository or include the build spec declaration as part of the build project
definition. Do not create a ZIP file that contains the repository's source code and
build spec file.

For build input stored in Amazon S3 buckets only, you must create a ZIP file that
contains the source code and, by convention, a build spec file named
buildspec.yml at the root (top level) or include the build
spec declaration as part of the build project definition.

If you want to use a different name for your build spec file, or you want to
reference a build spec in a location other than the root, you can specify a build
spec override as part of the build project definition. For more information, see
Build Spec File Name and Storage
Location.

Step 5: Create the Build
Project

In this step, you create a build project that AWS CodeBuild uses to run the build.
A build project defines how CodeBuild runs a build. It includes information such as where to get
the source code, the build environment to use, the build commands to run, and where
to store the build output. A build environment represents a combination of operating system, programming language runtime, and tools
that CodeBuild uses to run a build. The build environment is
expressed as a Docker image. (For more information, see the Docker Overview topic on
the Docker Docs website.) For this build environment, you instruct CodeBuild to use
a Docker image that contains a version of the Java Development Kit (JDK)
and Apache Maven.

You can work with CodeBuild in several ways: through the CodeBuild console, AWS CodePipeline,
the AWS CLI, or the AWS SDKs. This walkthrough demonstrates how to use
the CodeBuild console and the AWS CLI. To learn how to use CodePipeline, see Use AWS CodePipeline with AWS CodeBuild.
To learn how to use the AWS SDKs, see Run AWS CodeBuild Directly.

In the AWS region selector, choose a region that supports CodeBuild. For more information,
see CodeBuild in the "Regions and Endpoints" topic in the
Amazon Web Services General Reference.

If a CodeBuild information page is displayed, choose Create project. Otherwise, on the navigation pane, expand Build,
and then choose Build projects.

On the Create build project page, in Project configuration, for Project name, enter
a name for this build project (in this example, codebuild-demo-project). Build project names must be unique across each AWS
account. If you use a different name, be sure to use it throughout this walkthrough.

Note

On the Create build project page, you might see an error message similar to the following: User:
user-ARN is not authorized to perform: codebuild:ListProjects. This is most likely because you
signed in to the AWS Management Console as an IAM user that does not have sufficient
permissions to use CodeBuild in the console. To fix this, sign out of the
AWS Management Console, and then sign back in with credentials belonging to one of
the following IAM entities:

Your AWS root account. This is not recommended. For more information, see The Account Root
User in the IAM User Guide.

An IAM user in your AWS account with the AWS managed policies named AWSCodeBuildAdminAccess,
AmazonS3ReadOnlyAccess, and IAMFullAccess attached to that IAM user or to an IAM group that the
IAM user belongs to. If you do not have an IAM user or group in your AWS account with
these permissions, and you cannot add these
permissions to your IAM user or group, contact your AWS account administrator for
assistance. For more information, see AWS Managed (Predefined) Policies for
CodeBuild.

In Source, for Source provider, choose Amazon S3.

For Bucket, choose
codebuild-region-ID-account-ID-input-bucket.

For S3 object key, enter MessageUtil.zip.

In Environment, for Environment image, leave Managed image selected.

For Operating system, choose
Ubuntu.

For Runtime, choose Java.

For Runtime version, choose aws/codebuild/java:openjdk-8.

In Service role, leave New service role selected, and leave Role name
unchanged.

JSON-formatted data appears in the output. Copy the data to a file named create-project.json in a location on
the local computer or instance where the AWS CLI is installed. If you choose to use
a different file name, be sure to use it throughout this
walkthrough.

Modify the copied data to follow this format, and then save your
results:

Replace serviceIAMRole with the Amazon Resource
Name (ARN) of a CodeBuild service role (for example,
arn:aws:iam::account-ID:role/role-name).
To create one, see Create a CodeBuild Service Role.

In this data:

name represents a required identifier for this build project (in this example, codebuild-demo-project).
Build project names must be unique across all build projects in your account.

For source, type is a required value that
represents the source code's repository type (in this example,
S3 for an Amazon S3 bucket).

For source, location represents the path to
the source code (in this example, the input bucket name followed by the
ZIP file name).

For artifacts, type is a required value that
represents the build output artifact's repository type (in this example,
S3 for an Amazon S3 bucket).

For artifacts, location represents the name
of the output bucket you created or identified earlier (in this example,
codebuild-region-ID-account-ID-output-bucket).

For environment, type is a required value
that represents the type of build environment
(LINUX_CONTAINER is currently the only allowed
value).

For environment, image is a required value that represents the Docker image name and tag combination
this build project uses, as specified by the Docker image repository type (in this
example, aws/codebuild/java:openjdk-8 for a
Docker image in the CodeBuild Docker images repository). aws/codebuild/java is the name of the Docker image. openjdk-8 is
the tag of the Docker image.

For environment, computeType is a required value that represents the computing resources CodeBuild uses (in
this example, BUILD_GENERAL1_SMALL).

Note

Other available values in the original JSON-formatted data, such as
description, buildspec, auth
(including type and resource), path,
namespaceType, name (for
artifacts), packaging,
environmentVariables (including name and
value), timeoutInMinutes,
encryptionKey, and tags (including
key and value) are optional. They are not used
in this walkthrough, so they are not shown here. For more information, see
Create a Build Project (AWS CLI).

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

packaging represents how the build output artifact is stored in the output bucket. NONE means
that a folder is created in the output bucket. The build output artifact is stored
in that folder.

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

timeoutInMinutes represents the number of minutes after which CodeBuild stops the build if the build
has not been
completed. (The default is 60 minutes.)

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

environmentVariables represents any environment
variables that were declared and are available for CodeBuild to use
during the build.

encryptionKey represents the ARN of the AWS KMS customer master key (CMK) that CodeBuild used to
encrypt the build
output artifact.

arn represents the ARN of the build
project.

Note

After you run the create-project command, an error message similar to the following might be output: User:
user-ARN is not authorized to perform: codebuild:CreateProject. This is most likely because you
configured the AWS CLI with the credentials of an IAM user that does not have sufficient
permissions to use CodeBuild to create build projects. To fix this,
configure the AWS CLI with credentials belonging to one of the following IAM entities:

Your AWS root account. This is not recommended. For more information,
see The Account Root
User in the IAM User Guide.

An IAM user in your AWS account with the AWS managed policies named AWSCodeBuildAdminAccess,
AmazonS3ReadOnlyAccess, and IAMFullAccess attached to that IAM user or to an IAM group that the
IAM user belongs to. If you do not have an IAM user or group in your AWS account with
these permissions, and you cannot add these permissions
to your IAM user or group, contact your AWS account administrator for assistance.
For more information, see AWS Managed (Predefined) Policies for
CodeBuild.

Step 6: Run the Build

In this step, you instruct AWS CodeBuild to run the build with the settings in the
build project.

Step 7: View Summarized Build
Information

To view summarized build
information (console)

If the codebuild-demo-project:build-ID page is not displayed, then in the navigation
bar, choose Build history. Next, in the list of build projects, for Project, choose the Build
run link for codebuild-demo-project. There should be only one matching link. (If you have completed this
walkthrough before, choose the link in the Completed column for the most recent value.)

On the build details page, in Phase details, the
following list of build phases should be displayed, with
Succeeded in the Status
column:

SUBMITTED

PROVISIONING

DOWNLOAD_SOURCE

INSTALL

PRE_BUILD

BUILD

POST_BUILD

UPLOAD_ARTIFACTS

FINALIZING

COMPLETED

In Build Status, Succeeded should be displayed.

If you see In Progress instead,
choose the refresh button to see the latest progress.

Next to each build phase, the Duration value
indicates how long that build phase lasted. The
End time value indicates when that build phase
ended.

buildsNotFound represents the build IDs for any builds where
information is not available. In this example, it should be empty.

builds represents information about each build where
information is available. In this example, information about only one build
appears in the output.

phases represents the set of build phases CodeBuild runs during the build process. Information
about each build phase
is listed separately as startTime, endTime, and durationInSeconds (when the build phase started and
ended, expressed in Unix time format, and how long it lasted, in seconds), and phaseType such as (SUBMITTED,
PROVISIONING, DOWNLOAD_SOURCE, INSTALL, PRE_BUILD, BUILD,
POST_BUILD, UPLOAD_ARTIFACTS, FINALIZING, or COMPLETED) and phaseStatus (such
as SUCCEEDED, FAILED, FAULT, TIMED_OUT, IN_PROGRESS, or STOPPED).
The first time you run the batch-get-builds command, there might not be many (or any) phases. After
subsequent runs of the batch-get-builds command with the same build ID, more build phases should
appear in the output.

md5sum and sha256sum represent MD5 and SHA-256 hashes of the build's output artifact. These appear
in the output only if the build project's packaging value is set to ZIP. (You did not set this value in this
walkthrough.) You can use these hashes along with a checksum tool to confirm file
integrity and authenticity.

Note

You can also use the Amazon S3 console to view these hashes. Select
the box next to the build output artifact, and then choose
Actions,
Properties. In the
Properties pane, expand
Metadata, and view the values for
x-amz-meta-codebuild-content-md5 and
x-amz-meta-codebuild-content-sha256.
(In the Amazon S3 console, the build output artifact's
ETag value should not be interpreted to
be either the MD5 or SHA-256 hash.)

If you use the AWS SDKs to get these hashes, the values are
named codebuild-content-md5 and
codebuild-content-sha256.

endTime represents the time, in Unix time format,
when the build process ended.

Step 8: View Detailed Build
Information

In this step, you view detailed information about your build in CloudWatch Logs.

With the build details page still displayed from the previous step, the last
10,000 lines of the build log are displayed in Build logs.
To see the entire build log in CloudWatch Logs, choose the View entire
log link.

In the CloudWatch Logs log stream, you can browse the log events. By default, only
the
last set of log events is displayed. To see earlier log events, scroll to the
beginning of the list.

In this walkthrough, most of the log events contain verbose information about CodeBuild
downloading and installing build dependency files into
its build environment, which you probably don't care about. You can use the Filter events box to reduce the information
displayed. For example, if you enter "[INFO]" in the Filter events box, only those events that contain
[INFO] are displayed. For more information, see Filter and Pattern Syntax
in the Amazon CloudWatch User Guide.

Use your web browser to go to the deepLink location that appeared
in the output in the previous step (for example,
https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE).

In the CloudWatch Logs log stream, you can browse the log events. By default, only
the
last set of log events is displayed. To see earlier log events, scroll to the
beginning of the list.

In this walkthrough, most of the log events contain verbose information about CodeBuild
downloading and installing build dependency files into
its build environment, which you probably don't care about. You can use the Filter events box to reduce the information
displayed. For example, if you enter "[INFO]" in the Filter events box, only those events that contain
[INFO] are displayed. For more information, see Filter and Pattern Syntax
in the Amazon CloudWatch User Guide.

These portions of a CloudWatch Logs log stream pertain to this walkthrough.

With the CodeBuild console still open and the build details page still displayed from
the previous step, in Build Status,
choose the View artifacts link. This opens the folder in Amazon S3 for the build output artifact. (If the build
details page is not
displayed, in the navigation bar, choose Build history, and then choose the Build run link.)

Open the folder named target, where you find the build output artifact file named
messageUtil-1.0.jar.

Open the folder named target, where you find the build output artifact file named
messageUtil-1.0.jar.

Step 10: Clean Up

To prevent ongoing charges to your AWS account, you can delete the input bucket used
in this walkthrough. For instructions, see Deleting or Emptying a Bucket
in the Amazon Simple Storage Service Developer Guide.

If you are using the IAM user to delete this bucket instead of an AWS root account
or an administrator IAM user, the user must have
additional access permissions. (Using an AWS root account is not recommended.) Add
the following statement between the markers (### BEGIN
ADDING STATEMENT HERE ### and ### END ADDING STATEMENTS HERE ###) to an existing access policy for the user.
Ellipses (...) are used for brevity. Do not remove any statements in the existing access policy.
Do not enter these ellipses into the
policy.

Next Steps

In this walkthrough, you used AWS CodeBuild to build a set of Java class files into
a JAR
file. You then viewed the build's results.

You can now try using CodeBuild in your own scenarios by following the instructions
in Plan a Build. If
you don't feel ready yet, you might want to try building some of the samples. For
more information, see Samples.

Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's
Help pages for instructions.