# Use case-based samples for CodeBuild
You can use these use case-based samples to experiment with AWS CodeBuild:
[Cross-service samples](cross-service-samples.md)
A list of cross-service samples to experiment with AWS CodeBuild.
[Build badges sample](sample-build-badges.md)
Shows how to set up CodeBuild with build badges.
[Test report sample](sample-test-report-cli.md)
Uses the AWS CLI to create, run, and view the results of a test report.
[Docker samples for CodeBuild](sample-docker-section.md)
Shows how to use custom Docker images, publish Docker images to a repository in Amazon ECR, and use Docker images in a private registry.
[Host build output in an S3 bucket ](sample-disable-artifact-encryption.md)
Shows how to create a static website in an S3 bucket using unencrypted build artifacts.
[ Multiple inputs and outputs sample ](sample-multi-in-out.md)
Shows how to use multiple input sources and multiple output artifacts in a build project.
[ Parallel test execution samples ](sample-parallel-test.md)
Shows how to use the `codebuild-tests-run` CLI command to split and run tests across parallel execution environments.
[ Runtime versions in buildspec file sample ](sample-runtime-versions.md)
Shows how to specify runtimes and their versions in the buildspec file.
[Source version sample](sample-source-version.md)
Shows how to use a specific version of your source in a CodeBuild build project.
[Third-party source repository samples for CodeBuild](sample-third-party-source.md)
Shows how to create BitBucket, GitHub Enterprise Server, and GitHub pull requests with webhooks using CodeBuild.
[Set artifact names at build time using semantic versioning](sample-buildspec-artifact-naming.md)
Shows how to use semantic versioning to create an artifact name at build time.
# Cross-service samples for CodeBuild
You can use these cross-service samples to experiment with AWS CodeBuild:
[Amazon ECR sample](sample-ecr.md)
Uses a Docker image in an Amazon ECR repository to use Apache Maven to produce a single JAR file. The sample instructions will show you how to create and push a Docker image to Amazon ECR, create a Go project, build the project, run the project, and set up permissions to allow CodeBuild to connect to Amazon ECR.
[Amazon EFS sample](sample-efs.md)
Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system. The sample instructions will show you how to create a Amazon VPC, create file system in the Amazon VPC, create and build a project that uses the Amazon VPC, and then review the generated project file and variables.
[AWS CodePipeline samples](sample-codepipeline.md)
Shows how to use AWS CodePipeline to create a build with batch builds as well as multiple input sources and multiple output artifacts. Included in this section are example JSON files that show pipeline structures that create batch builds with separate artifacts, and combined artifacts. An additonal JSON sample is provided that show the pipeline structure with multiple input sources and multiple output artifacts.
[AWS Config sample](how-to-integrate-config.md)
Shows how to set up AWS Config. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config. The sample instructions will show you the prerequisites for integrating with AWS Config, the steps to set up AWS Config, and the steps to look up CodeBuild projects and data in AWS Config.
[Build notifications sample](sample-build-notifications.md)
Uses Apache Maven to produce a single JAR file. Sends a build notification to subscribers of an Amazon SNS topic. The sample instructions show you how to set up permissions so that CodeBuild can communicate with Amazon SNS and CloudWatch, how to create and identify CodeBuild topics in Amazon SNS, how to subscribe recipients to the topic, and how to set up rules in CloudWatch.
# Amazon ECR sample for CodeBuild
This sample uses a Docker image in an Amazon Elastic Container Registry (Amazon ECR) image repository to build a sample Go project.
**Important**
Running this sample might result in charges to your AWS account. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing).
**Topics**
+ [Run the Amazon ECR sample](#sample-ecr-running)
## Run the Amazon ECR sample
Use the following instructions to run the Amazon ECR sample for CodeBuild.
**To run this sample**
1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the [Run the 'Publish Docker image to Amazon ECR' sample](sample-docker.md#sample-docker-running) section of the ['Publish Docker image to Amazon ECR' sample](sample-docker.md).
1. Create a Go project:
1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Create a build project, run the build, and view related build information.
If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "sample-go-project",
"source": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-input-bucket/GoSample.zip"
},
"artifacts": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-output-bucket",
"packaging": "ZIP",
"name": "GoOutputArtifact.zip"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/standard:5.0",
"computeType": "BUILD_GENERAL1_SMALL"
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
1. To get the build output artifact, open your S3 output bucket.
1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file. In the extracted contents, get the `hello` file.
1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment.
+ Your project uses CodeBuild credentials to pull Amazon ECR images. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`.
+ Your project uses a cross-account Amazon ECR image. In this case, your project must use its service role to pull Amazon ECR images. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`.
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. In the list of repository names, choose the name of the repository you created or selected.
1. From the navigation pane, choose **Permissions**, choose **Edit**, and then choose **Add statement**.
1. For **Statement name**, enter an identifier (for example, **CodeBuildAccess**).
1. For **Effect**, leave **Allow** selected. This indicates that you want to allow access to another AWS account.
1. For **Principal**, do one of the following:
+ If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild.amazonaws.com**.
+ If your project uses a cross-account Amazon ECR image, for **AWS account IDs**, enter IDs of the AWS accounts that you want to give access.
1. Skip the **All IAM entities** list.
1. For **Action**, select the pull-only actions: **ecr:GetDownloadUrlForLayer**, **ecr:BatchGetImage**, and **ecr:BatchCheckLayerAvailability**.
1. For **Conditions**, add the following:
```
{
"StringEquals":{
"aws:SourceAccount":"",
"aws:SourceArn":"arn:aws:codebuild:::project/"
}
}
```
1. Choose **Save**.
This policy is displayed in **Permissions**. The principal is what you entered for **Principal** in step 3 of this procedure:
+ If your project uses CodeBuild credentials to pull an Amazon ECR image, `"codebuild.amazonaws.com"` appears under **Service principals**.
+ If your project uses a cross-account Amazon ECR image, the ID of the AWS account that you want to give access appears under **AWS Account IDs**.
The following sample policy uses both CodeBuild credentials and a cross-account Amazon ECR image.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "CodeBuildAccessPrincipal",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:codebuild:us-east-1:111122223333:project/MyProject",
"aws:SourceAccount": "111122223333"
}
}
},
{
"Sid": "CodeBuildAccessCrossAccount",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
],
"Resource": "*"
}
]
}
```
------
+ If your projects use CodeBuild credentials and you would like your CodeBuild projects to have open access to the Amazon ECR repository, you can omit the `Condition` keys and add the following sample policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "CodeBuildAccessPrincipal",
"Effect": "Allow",
"Resource": [
"arn:aws:codecommit:us-east-2:111122223333:MySharedDemoRepo"
],
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
]
},
{
"Sid": "CodeBuildAccessCrossAccount",
"Effect": "Allow",
"Resource": [
"arn:aws:codecommit:us-east-2:111122223333:MySharedDemoRepo"
],
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
]
}
]
}
```
------
1. Create a build project, run the build, and view build information.
If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "amazon-ecr-sample-project",
"source": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-input-bucket/GoSample.zip"
},
"artifacts": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-output-bucket",
"packaging": "ZIP",
"name": "GoOutputArtifact.zip"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "account-ID.dkr.ecr.region-ID.amazonaws.com/your-Amazon-ECR-repo-name:tag",
"computeType": "BUILD_GENERAL1_SMALL"
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
1. To get the build output artifact, open your S3 output bucket.
1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file. In the extracted contents, get the `hello` file.
### Go project structure
This sample assumes this directory structure.
```
(root directory name)
├── buildspec.yml
└── hello.go
```
### Go project files
This sample uses these files.
`buildspec.yml` (in `(root directory name)`)
```
version: 0.2
phases:
install:
runtime-versions:
golang: 1.13
build:
commands:
- echo Build started on `date`
- echo Compiling the Go code
- go build hello.go
post_build:
commands:
- echo Build completed on `date`
artifacts:
files:
- hello
```
`hello.go` (in `(root directory name)`)
```
package main
import "fmt"
func main() {
fmt.Println("hello world")
fmt.Println("1+1 =", 1+1)
fmt.Println("7.0/3.0 =", 7.0/3.0)
fmt.Println(true && false)
fmt.Println(true || false)
fmt.Println(!true)
}
```
# Amazon Elastic File System sample for AWS CodeBuild
You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed. It has a simple web services interface that you can use to create and configure file systems. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations. For more information, see [What is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*.
This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repository.
Data in transit for your file system is encrypted. To encrypt data in transit using a different image, see [Encrypting data in transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html).
**Topics**
+ [Use AWS CodeBuild with Amazon Elastic File System](#sample-efs-high-level-steps)
+ [Troubleshoot the Amazon EFS integration](sample-efs-troubleshooting.md)
## Use AWS CodeBuild with Amazon Elastic File System
The sample covers the four high-level steps required to use Amazon EFS with AWS CodeBuild. They are:
1. Create a virtual private cloud (VPC) in your AWS account.
1. Create a file system that uses this VPC.
1. Create and build a CodeBuild project that uses the VPC. The CodeBuild project uses the following to identify the file system:
+ A unique file system identifier. You choose the identifier when you specify the file system in your build project.
+ The file system ID. The ID is displayed when you view your file system in the Amazon EFS console.
+ A mount point. This is a directory in your Docker container that mounts the file system.
+ Mount options. These include details about how to mount the file system.
1. Review the build project to ensure that the correct project files and variables were generated.
**Note**
A file system created in Amazon EFS is supported on Linux platforms only.
**Topics**
+ [Step 1: Create a VPC using CloudFormation](#sample-efs-create-vpc)
+ [Step 2: Create an Amazon Elastic File System file system with your VPC](#sample-efs-create-efs)
+ [Step 3: Create a CodeBuild project to use with Amazon EFS](#sample-efs-create-acb)
+ [Step 4: Review the build project](#sample-efs-summary)
### Step 1: Create a VPC using CloudFormation
Create your VPC with an CloudFormation template.
1. Follow the instructions in [CloudFormation VPC template](cloudformation-vpc-template.md) to use CloudFormation to create a VPC.
**Note**
The VPC created by this CloudFormation template has two private subnets and two public subnets. You must only use private subnets when you use AWS CodeBuild to mount the file system you created in Amazon EFS. If you use one of the public subnets, the build fails.
1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. Choose the VPC you created with CloudFormation.
1. On the **Description** tab, make a note of the name of your VPC and its ID. Both are required when you create your AWS CodeBuild project later in this sample.
### Step 2: Create an Amazon Elastic File System file system with your VPC
Create a simple Amazon EFS file system for this sample using the VPC you created earlier.
1. Sign in to the AWS Management Console and open the Amazon EFS console at [ https://console.aws.amazon.com/efs/](https://console.aws.amazon.com/efs/).
1. Choose **Create file system**.
1. From **VPC**, choose the VPC name you noted earlier in this sample.
1. Leave the Availability Zones associated with your subnets selected.
1. Choose **Next Step**.
1. In **Add tags**, for the default **Name** key, in **Value**, enter the name of your Amazon EFS file system.
1. Keep **Bursting** and **General Purpose** selected as your default performance and throughput modes, and then choose **Next Step**.
1. For **Configure client access**, choose **Next Step**.
1. Choose **Create File System**.
1. (Optional) We recommend adding a policy to your Amazon EFS file system that enforces encryption of data in transit. In the Amazon EFS console, choose **File system policy**, choose **Edit**, select the box labeled **Enforce in-transit encryption for all clients**, and then choose **Save**.
### Step 3: Create a CodeBuild project to use with Amazon EFS
Create a AWS CodeBuild project that uses the VPC you created earlier in this sample. When the build is run, it mounts the Amazon EFS file system created earlier. Next, it stores the .jar file created by your Java application in your file system's mount point directory.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. From the navigation pane, choose **Build projects**, and then choose **Create build project**.
1. In **Project name**, enter a name for your project.
1. From **Source provider**, choose the repository that contains the Java application you want to build.
1. Enter information, such as a repository URL, that CodeBuild uses to locate your application. The options are different for each source provider. For more information, see [Choose source provider](create-project.md#create-project-source-provider).
1. From **Environment image**, choose **Managed image**.
1. From **Operating system**, choose **Amazon Linux 2**.
1. From **Runtime(s)**, choose **Standard**.
1. From **Image**, choose **aws/codebuild/amazonlinux-x86\$164-standard:4.0**.
1. From **Environment type**, choose **Linux**.
1. Under **Service role**, choose **New service role**. In **Role name**, enter a name for the role CodeBuild creates for you.
1. Expand **Additional configuration**.
1. Select **Enable this flag if you want to build Docker images or want your builds to get elevated privileges**.
**Note**
By default, Docker daemon is enabled for non-VPC builds. If you would like to use Docker containers for VPC builds, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website and enable privileged mode. Also, Windows does not support privileged mode.
1. From **VPC**, choose the VPC ID.
1. From **Subnets**, choose one or more of the private subnets associated with your VPC. You must use private subnets in a build that mounts an Amazon EFS file system. If you use a public subnet, the build fails.
1. From **Security Groups**, choose the default security group.
1. In **File systems**, enter the following information:
+ For **Identifier**, enter a unique file system identifier. It must be fewer than 129 characters and contain only alphanumeric characters and underscores. CodeBuild uses this identifier to create an environment variable that identifies the elastic file system. The environment variable format is `CODEBUILD_` in capital letters. For example, if you enter `my_efs`, the environment variable is `CODEBUILD_MY_EFS`.
+ For **ID**, choose the file system ID.
+ (Optional) Enter a directory in the file system. CodeBuild mounts this directory. If you leave **Directory path** blank, CodeBuild mounts the entire file system. The path is relative to the root of the file system.
+ For **Mount point**, enter the absolute path of the directory in your build container where the file system is mounted. If this directory does not exist, CodeBuild creates it during the build.
+ (Optional) Enter mount options. If you leave **Mount options** blank, CodeBuild uses its default mount options:
```
nfsvers=4.1
rsize=1048576
wsize=1048576
hard
timeo=600
retrans=2
```
For more information, see [Recommended NFS Mount Options](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-nfs-mount-settings.html) in the *Amazon Elastic File System User Guide*.
1. For **Build specification**, choose **Insert build commands**, and then choose **Switch to editor**.
1. Enter the following build spec commands into the editor. Replace `` with the identifier you entered in step 17. Use capital letters (for example, `CODEBUILD_MY_EFS`).
```
version: 0.2
phases:
install:
runtime-versions:
java: corretto11
build:
commands:
- mvn compile -Dgpg.skip=true -Dmaven.repo.local=$CODEBUILD_
```
1. Use the default values for all other settings, and then choose **Create build project**. When your build is complete, the console page for your project is displayed.
1. Choose **Start build**.
### Step 4: Review the build project
After your AWS CodeBuild project is built:
+ You have a .jar file created by your Java application that is built to your Amazon EFS file system under your mount point directory.
+ An environment variable that identifies your file system is created using the file system identifier you entered when you created the project.
For more information, see [Mounting file systems](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs.html) in the *Amazon Elastic File System User Guide*.
# Troubleshoot the Amazon EFS integration
The following are errors you might encounter when setting up Amazon EFS with CodeBuild.
**Topics**
+ [CLIENT\$1ERROR: mounting '127.0.0.1:/' failed. permission denied](#sample-efs-troubleshooting.permission-denied)
+ [CLIENT\$1ERROR: mounting '127.0.0.1:/' failed. connection reset by peer](#sample-efs-troubleshooting.connection-reset)
+ [VPC\$1CLIENT\$1ERROR: Unexpected EC2 error: UnauthorizedOperation](#sample-efs-troubleshooting.unauthorized-operation)
## CLIENT\$1ERROR: mounting '127.0.0.1:/' failed. permission denied
IAM authorization is not supported for mounting Amazon EFS with CodeBuild. If you are using a custom Amazon EFS file system policy, you will need to grant read and write access to all IAM principals. For example:
```
"Principal": {
"AWS": "*"
}
```
## CLIENT\$1ERROR: mounting '127.0.0.1:/' failed. connection reset by peer
There are two possible causes for this error:
+ The CodeBuild VPC subnet is in a different availability zone than the Amazon EFS mount target. You can resolve this by adding a VPC subnet in the same availability zone as the Amazon EFS mount target.
+ The security group does not have permissions to communicate with Amazon EFS. You can resolve this by adding an inbound rule to allow all traffic from either the VPC (add the primary CIDR block for your VPC), or the security group itself.
## VPC\$1CLIENT\$1ERROR: Unexpected EC2 error: UnauthorizedOperation
This error occurs when all of the subnets in your VPC configuration for the CodeBuild project are public subnets. You must have at least one private subnet in the VPC to ensure network connectivity.
# AWS CodePipeline samples for CodeBuild
This section describes sample integrations between CodePipeline and CodeBuild.
| Sample | Description |
| --- | --- |
| [Samples of CodePipeline/CodeBuild integrations and batch builds](#sample-pipeline-batch) | These samples demonstrate how to use AWS CodePipeline to create a build project that uses batch builds. |
| [Sample of a CodePipeline/CodeBuild integration with multiple input sources and output artifacts](#sample-pipeline-multi-input-output) | This sample demonstrates how to use AWS CodePipeline to create a build project that uses multiple input sources to create multiple output artifacts. |
## Samples of CodePipeline/CodeBuild integrations and batch builds
AWS CodeBuild supports batch builds. The following samples demonstrate how to use AWS CodePipeline to create a build project that uses batch builds.
You can use a JSON-formatted file that defines the structure of your pipeline, and then use it with the AWS CLI to create the pipeline. For more information, see [AWS CodePipeline Pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*.
### Batch build with individual artifacts
Use the following JSON file as an example of a pipeline structure that creates a batch build with separate artifacts. To enable batch builds in CodePipeline, set the `BatchEnabled` parameter of the `configuration` object to `true`.
```
{
"pipeline": {
"roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name",
"stages": [
{
"name": "Source",
"actions": [
{
"inputArtifacts": [],
"name": "Source1",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source1"
}
],
"configuration": {
"S3Bucket": "",
"S3ObjectKey": "my-source-code-file-name.zip"
},
"runOrder": 1
},
{
"inputArtifacts": [],
"name": "Source2",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source2"
}
],
"configuration": {
"S3Bucket": "",
"S3ObjectKey": "my-other-source-code-file-name.zip"
},
"runOrder": 1
}
]
},
{
"name": "Build",
"actions": [
{
"inputArtifacts": [
{
"name": "source1"
},
{
"name": "source2"
}
],
"name": "Build",
"actionTypeId": {
"category": "Build",
"owner": "AWS",
"version": "1",
"provider": "CodeBuild"
},
"outputArtifacts": [
{
"name": "build1"
},
{
"name": "build1_artifact1"
},
{
"name": "build1_artifact2"
},
{
"name": "build2_artifact1"
},
{
"name": "build2_artifact2"
}
],
"configuration": {
"ProjectName": "my-build-project-name",
"PrimarySource": "source1",
"BatchEnabled": "true"
},
"runOrder": 1
}
]
}
],
"artifactStore": {
"type": "S3",
"location": ""
},
"name": "my-pipeline-name",
"version": 1
}
}
```
The following is an example of a CodeBuild buildspec file that will work with this pipeline configuration.
```
version: 0.2
batch:
build-list:
- identifier: build1
env:
compute-type: BUILD_GENERAL1_SMALL
- identifier: build2
env:
compute-type: BUILD_GENERAL1_MEDIUM
phases:
build:
commands:
- echo 'file' > output_file
artifacts:
files:
- output_file
secondary-artifacts:
artifact1:
files:
- output_file
artifact2:
files:
- output_file
```
The names of the output artifacts specified in the pipeline's JSON file must match the identifier of the builds and artifacts defined in your buildspec file. The syntax is *buildIdentifier* for the primary artifacts, and *buildIdentifier*\$1*artifactIdentifier* for the secondary artifacts.
For example, for output artifact name `build1`, CodeBuild will upload the primary artifact of `build1` to the location of `build1`. For output name `build1_artifact1`, CodeBuild will upload the secondary artifact `artifact1` of `build1` to the location of `build1_artifact1`, and so on. If only one output location is specified, the name should be *buildIdentifier* only.
After you create the JSON file, you can create your pipeline. Use the AWS CLI to run the **create-pipeline** command and pass the file to the `--cli-input-json` parameter. For more information, see [Create a pipeline (CLI)](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-cli) in the *AWS CodePipeline User Guide*.
### Batch build with combined artifacts
Use the following JSON file as an example of a pipeline structure that creates a batch build with combined artifacts. To enable batch builds in CodePipeline, set the `BatchEnabled` parameter of the `configuration` object to `true`. To combine the build artifacts into the same location, set the `CombineArtifacts` parameter of the `configuration` object to `true`.
```
{
"pipeline": {
"roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name",
"stages": [
{
"name": "Source",
"actions": [
{
"inputArtifacts": [],
"name": "Source1",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source1"
}
],
"configuration": {
"S3Bucket": "",
"S3ObjectKey": "my-source-code-file-name.zip"
},
"runOrder": 1
},
{
"inputArtifacts": [],
"name": "Source2",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source2"
}
],
"configuration": {
"S3Bucket": "",
"S3ObjectKey": "my-other-source-code-file-name.zip"
},
"runOrder": 1
}
]
},
{
"name": "Build",
"actions": [
{
"inputArtifacts": [
{
"name": "source1"
},
{
"name": "source2"
}
],
"name": "Build",
"actionTypeId": {
"category": "Build",
"owner": "AWS",
"version": "1",
"provider": "CodeBuild"
},
"outputArtifacts": [
{
"name": "output1 "
}
],
"configuration": {
"ProjectName": "my-build-project-name",
"PrimarySource": "source1",
"BatchEnabled": "true",
"CombineArtifacts": "true"
},
"runOrder": 1
}
]
}
],
"artifactStore": {
"type": "S3",
"location": ""
},
"name": "my-pipeline-name",
"version": 1
}
}
```
The following is an example of a CodeBuild buildspec file that will work with this pipeline configuration.
```
version: 0.2
batch:
build-list:
- identifier: build1
env:
compute-type: BUILD_GENERAL1_SMALL
- identifier: build2
env:
compute-type: BUILD_GENERAL1_MEDIUM
phases:
build:
commands:
- echo 'file' > output_file
artifacts:
files:
- output_file
```
If combined artifacts is enabled for the batch build, there is only one output allowed. CodeBuild will combine the primary artifacts of all the builds into one single ZIP file.
After you create the JSON file, you can create your pipeline. Use the AWS CLI to run the **create-pipeline** command and pass the file to the `--cli-input-json` parameter. For more information, see [Create a pipeline (CLI)](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-cli) in the *AWS CodePipeline User Guide*.
## Sample of a CodePipeline/CodeBuild integration with multiple input sources and output artifacts
An AWS CodeBuild project can take more than one input source. It can also create more than one output artifact. This sample demonstrates how to use AWS CodePipeline to create a build project that uses multiple input sources to create multiple output artifacts. For more information, see [Multiple input sources and output artifacts sample](sample-multi-in-out.md).
You can use a JSON-formatted file that defines the structure of your pipeline, and then use it with the AWS CLI to create the pipeline. Use the following JSON file as an example of a pipeline structure that creates a build with more than one input source and more than one output artifact. Later in this sample you see how this file specifies the multiple inputs and outputs. For more information, see [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*.
```
{
"pipeline": {
"roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name",
"stages": [
{
"name": "Source",
"actions": [
{
"inputArtifacts": [],
"name": "Source1",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source1"
}
],
"configuration": {
"S3Bucket": "my-input-bucket-name",
"S3ObjectKey": "my-source-code-file-name.zip"
},
"runOrder": 1
},
{
"inputArtifacts": [],
"name": "Source2",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"version": "1",
"provider": "S3"
},
"outputArtifacts": [
{
"name": "source2"
}
],
"configuration": {
"S3Bucket": "my-other-input-bucket-name",
"S3ObjectKey": "my-other-source-code-file-name.zip"
},
"runOrder": 1
}
]
},
{
"name": "Build",
"actions": [
{
"inputArtifacts": [
{
"name": "source1"
},
{
"name": "source2"
}
],
"name": "Build",
"actionTypeId": {
"category": "Build",
"owner": "AWS",
"version": "1",
"provider": "AWS CodeBuild"
},
"outputArtifacts": [
{
"name": "artifact1"
},
{
"name": "artifact2"
}
],
"configuration": {
"ProjectName": "my-build-project-name",
"PrimarySource": "source1"
},
"runOrder": 1
}
]
}
],
"artifactStore": {
"type": "S3",
"location": "AWS-CodePipeline-internal-bucket-name"
},
"name": "my-pipeline-name",
"version": 1
}
}
```
In this JSON file:
+ One of your input sources must be designated the `PrimarySource`. This source is the directory where CodeBuild looks for and runs your buildspec file. The keyword `PrimarySource` is used to specify the primary source in the `configuration` section of the CodeBuild stage in the JSON file.
+ Each input source is installed in its own directory. This directory is stored in the built-in environment variable `$CODEBUILD_SRC_DIR` for the primary source and `$CODEBUILD_SRC_DIR_yourInputArtifactName` for all other sources. For the pipeline in this sample, the two input source directories are `$CODEBUILD_SRC_DIR` and `$CODEBUILD_SRC_DIR_source2`. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md).
+ The names of the output artifacts specified in the pipeline's JSON file must match the names of the secondary artifacts defined in your buildspec file. This pipeline uses the following buildspec file. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax).
```
version: 0.2
phases:
build:
commands:
- touch source1_file
- cd $CODEBUILD_SRC_DIR_source2
- touch source2_file
artifacts:
files:
- '**/*'
secondary-artifacts:
artifact1:
base-directory: $CODEBUILD_SRC_DIR
files:
- source1_file
artifact2:
base-directory: $CODEBUILD_SRC_DIR_source2
files:
- source2_file
```
After you create the JSON file, you can create your pipeline. Use the AWS CLI to run the **create-pipeline** command and pass the file to the `--cli-input-json` parameter. For more information, see [Create a pipeline (CLI)](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-cli) in the *AWS CodePipeline User Guide*.
# AWS Config sample with CodeBuild
AWS Config provides an inventory of your AWS resources and a history of configuration changes to these resources. AWS Config now supports AWS CodeBuild as an AWS resource, which means the service can track your CodeBuild projects. For more information about AWS Config, see [What is AWS Config?](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) in the *AWS Config Developer Guide*.
You can see the following information about CodeBuild resources on the **Resource Inventory** page in the AWS Config console:
+ A timeline of your CodeBuild configuration changes.
+ Configuration details for each CodeBuild project.
+ Relationships with other AWS resources.
+ A list of changes to your CodeBuild projects.
**Topics**
+ [Use CodeBuild with AWS Config](#how-to-integrate-config-run)
+ [Step 3: View AWS CodeBuild data in the AWS Config console](#viewing-config-details)
## Use CodeBuild with AWS Config
The procedures in this topic show you how to set up AWS Config and look up CodeBuild projects.
**Topics**
+ [Prerequisites](#how-to-create-a-build-project)
+ [Step 1: Set up AWS Config](#setup-config)
+ [Step 2: Look up AWS CodeBuild projects](#lookup-projects)
### Prerequisites
Create your AWS CodeBuild project. For instructions, see [Create a build project](create-project.md).
### Step 1: Set up AWS Config
+ [Setting up AWS Config (console)](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html)
+ [Setting up AWS Config (AWS CLI)](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html)
**Note**
After you complete setup, it might take up to 10 minutes before you can see AWS CodeBuild projects in the AWS Config console.
### Step 2: Look up AWS CodeBuild projects
1. Sign in to the AWS Management Console and open the AWS Config console at [https://console.aws.amazon.com/config](https://console.aws.amazon.com/config).
1. On the **Resource inventory** page, select **AWS CodeBuild Project** under **Resource type**. Scroll down and select the **CodeBuild project** check box.
1. Choose **Look up**.
1. After the list of CodeBuild projects is added, choose the CodeBuild project name link in the **Config timeline** column.
## Step 3: View AWS CodeBuild data in the AWS Config console
When you look up resources on the **Resource inventory** page, you can choose the AWS Config timeline to view details about your CodeBuild project. The details page for a resource provides information about the configuration, relationships, and number of changes made to that resource.
The blocks at the top of the page are collectively called the timeline. The timeline shows the date and time that the recording was made.
For more information, see [Viewing configuration details in the AWS Config console](https://docs.aws.amazon.com/config/latest/developerguide/view-manage-resource-console.html) in the *AWS Config Developer Guide*.
# Build notifications sample for CodeBuild
Amazon CloudWatch Events has built-in support for AWS CodeBuild. CloudWatch Events is a stream of system events describing changes in your AWS resources. With CloudWatch Events, you write declarative rules to associate events of interest with automated actions to be taken. This sample uses Amazon CloudWatch Events and Amazon Simple Notification Service (Amazon SNS) to send build notifications to subscribers whenever builds succeed, fail, go from one build phase to another, or any combination of these events.
**Important**
Running this sample might result in charges to your AWS account. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon CloudWatch and Amazon SNS. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS pricing](http://aws.amazon.com/sns/pricing).
**Topics**
+ [Run the build notifications sample](#sample-build-notifications-running)
+ [Build notifications input format reference](sample-build-notifications-ref.md)
## Run the build notifications sample
Use the following procedure to run the build notifications sample.
**To run this sample**
1. If you already have a topic set up and subscribed to in Amazon SNS that you want to use for this sample, skip ahead to step 4. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator user to work with Amazon SNS, add the following statement (between *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1* and *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1*) to the user (or IAM group the user is associated with). Using an AWS root account is not recommended. This statement enables viewing, creating, subscribing, and testing the sending of notifications to topics in Amazon SNS. Ellipses (`...`) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the existing policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:CreateTopic",
"sns:GetTopicAttributes",
"sns:List*",
"sns:Publish",
"sns:SetTopicAttributes",
"sns:Subscribe"
],
"Resource": "*"
}
]
}
```
------
**Note**
The IAM entity that modifies this policy must have permission in IAM to modify policies.
For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*.
1. Create or identify a topic in Amazon SNS. AWS CodeBuild uses CloudWatch Events to send build notifications to this topic through Amazon SNS.
To create a topic:
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns](https://console.aws.amazon.com/sns).
1. Choose **Create topic**.
1. In **Create new topic**, for **Topic name**, enter a name for the topic (for example, **CodeBuildDemoTopic**). (If you choose a different name, substitute it throughout this sample.)
1. Choose **Create topic**.
1. On the **Topic details: CodeBuildDemoTopic** page, copy the **Topic ARN** value. You need this value for the next step.
![\[The Topic ARN value.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/topic-arn.png)
For more information, see [Create a topic](https://docs.aws.amazon.com/sns/latest/dg/CreateTopic.html) in the *Amazon SNS Developer Guide*.
1. Subscribe one or more recipients to the topic to receive email notifications.
To subscribe a recipient to a topic:
1. With the Amazon SNS console open from the previous step, in the navigation pane, choose **Subscriptions**, and then choose **Create subscription**.
1. In **Create subscription**, for **Topic ARN**, paste the topic ARN you copied from the previous step.
1. For **Protocol**, choose **Email**.
1. For **Endpoint**, enter the recipient's full email address.
![\[The subscription configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-subscription.png)
1. Choose **Create Subscription**.
1. Amazon SNS sends a subscription confirmation email to the recipient. To begin receiving email notifications, the recipient must choose the **Confirm subscription** link in the subscription confirmation email. After the recipient clicks the link, if successfully subscribed, Amazon SNS displays a confirmation message in the recipient's web browser.
For more information, see [Subscribe to a topic](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html) in the *Amazon SNS Developer Guide*.
1. If you are using an user instead of an AWS root account or an administrator user to work with CloudWatch Events, add the following statement (between *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1* and *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1*) to the user (or IAM group the user is associated with). Using an AWS root account is not recommended. This statement is used to allow the user to work with CloudWatch Events. Ellipses (`...`) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the existing policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"events:*",
"iam:PassRole"
],
"Resource": "arn:aws:iam::*:role/Service*"
}
]
}
```
------
**Note**
The IAM entity that modifies this policy must have permission in IAM to modify policies.
For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*.
1. Create a rule in CloudWatch Events. To do this, open the CloudWatch console, at [https://console.aws.amazon.com/cloudwatch](https://console.aws.amazon.com/cloudwatch).
1. In the navigation pane, under **Events**, choose **Rules**, and then choose **Create rule**.
1. On the **Step 1: Create rule page**, **Event Pattern** and **Build event pattern to match events by service** should already be selected.
1. For **Service Name**, choose **CodeBuild**. For **Event Type**, **All Events** should already be selected.
1. The following code should be displayed in **Event Pattern Preview**:
```
{
"source": [
"aws.codebuild"
]
}
```
1. Choose **Edit** and replace the code in **Event Pattern Preview** with one of the following two rule patterns.
This first rule pattern triggers an event when a build starts or completes for the specified build projects in AWS CodeBuild.
```
{
"source": [
"aws.codebuild"
],
"detail-type": [
"CodeBuild Build State Change"
],
"detail": {
"build-status": [
"IN_PROGRESS",
"SUCCEEDED",
"FAILED",
"STOPPED"
],
"project-name": [
"my-demo-project-1",
"my-demo-project-2"
]
}
}
```
In the preceding rule, make the following code changes as needed.
+ To trigger an event when a build starts or completes, either leave all of the values as shown in the `build-status` array, or remove the `build-status` array altogether.
+ To trigger an event only when a build completes, remove `IN_PROGRESS` from the `build-status` array.
+ To trigger an event only when a build starts, remove all of the values except `IN_PROGRESS` from the `build-status` array.
+ To trigger events for all build projects, remove the `project-name` array altogether.
+ To trigger events only for individual build projects, specify the name of each build project in the `project-name` array.
This second rule pattern triggers an event whenever a build moves from one build phase to another for the specified build projects in AWS CodeBuild.
```
{
"source": [
"aws.codebuild"
],
"detail-type": [
"CodeBuild Build Phase Change"
],
"detail": {
"completed-phase": [
"SUBMITTED",
"PROVISIONING",
"DOWNLOAD_SOURCE",
"INSTALL",
"PRE_BUILD",
"BUILD",
"POST_BUILD",
"UPLOAD_ARTIFACTS",
"FINALIZING"
],
"completed-phase-status": [
"TIMED_OUT",
"STOPPED",
"FAILED",
"SUCCEEDED",
"FAULT",
"CLIENT_ERROR"
],
"project-name": [
"my-demo-project-1",
"my-demo-project-2"
]
}
}
```
In the preceding rule, make the following code changes as needed.
+ To trigger an event for every build phase change (which might send up to nine notifications for each build), either leave all of the values as shown in the `completed-phase` array, or remove the `completed-phase` array altogether.
+ To trigger events only for individual build phase changes, remove the name of each build phase in the `completed-phase` array that you do not want to trigger an event for.
+ To trigger an event for every build phase status change, either leave all of the values as shown in the `completed-phase-status` array, or remove the `completed-phase-status` array altogether.
+ To trigger events only for individual build phase status changes, remove the name of each build phase status in the `completed-phase-status` array that you do not want to trigger an event for.
+ To trigger events for all build projects, remove the `project-name` array.
+ To trigger events for individual build projects, specify the name of each build project in the `project-name` array.
For more information about event patterns, see [Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/filtering-examples-structure.html) in the Amazon EventBridge User Guide.
For more information about filtering with event patterns, see [Content-based Filtering with Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/content-filtering-with-event-patterns.html) in the Amazon EventBridge User Guide.
**Note**
If you want to trigger events for both build state changes and build phase changes, you must create two separate rules: one for build state changes and another for build phase changes. If you try to combine both rules into a single rule, the combined rule might produce unexpected results or stop working altogether.
When you have finished replacing the code, choose **Save**.
1. For **Targets**, choose **Add target**.
1. In the list of targets, choose **SNS topic**.
1. For **Topic**, choose the topic you identified or created earlier.
1. Expand **Configure input**, and then choose **Input Transformer**.
1. In the **Input Path** box, enter one of the following input paths.
For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following.
```
{"build-id":"$.detail.build-id","project-name":"$.detail.project-name","build-status":"$.detail.build-status"}
```
For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following.
```
{"build-id":"$.detail.build-id","project-name":"$.detail.project-name","completed-phase":"$.detail.completed-phase","completed-phase-status":"$.detail.completed-phase-status"}
```
To get other types of information, see the [Build notifications input format reference](sample-build-notifications-ref.md).
1. In the **Input Template** box, enter one of the following input templates.
For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following.
```
"Build '' for build project '' has reached the build status of ''."
```
For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following.
```
"Build '' for build project '' has completed the build phase of '' with a status of ''."
```
1. Choose **Configure details**.
1. On the **Step 2: Configure rule details** page, enter a name and an optional description. For **State**, leave **Enabled** selected.
1. Choose **Create rule**.
1. Create build projects, run the builds, and view build information.
1. Confirm that CodeBuild is now successfully sending build notifications. For example, check to see if the build notification emails are now in your inbox.
To change a rule's behavior, in the CloudWatch console, choose the rule you want to change, choose **Actions**, and then choose **Edit**. Make changes to the rule, choose **Configure details**, and then choose **Update rule**.
To stop using a rule to send build notifications, in the CloudWatch console, choose the rule you want to stop using, choose **Actions**, and then choose **Disable**.
To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, choose **Actions**, and then choose **Delete**.
# Build notifications input format reference
CloudWatch delivers notifications in JSON format.
Build state change notifications use the following format:
```
{
"version": "0",
"id": "c030038d-8c4d-6141-9545-00ff7b7153EX",
"detail-type": "CodeBuild Build State Change",
"source": "aws.codebuild",
"account": "123456789012",
"time": "2017-09-01T16:14:28Z",
"region": "us-west-2",
"resources":[
"arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX"
],
"detail":{
"build-status": "SUCCEEDED",
"project-name": "my-sample-project",
"build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX",
"additional-information": {
"artifact": {
"md5sum": "da9c44c8a9a3cd4b443126e823168fEX",
"sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX",
"location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip"
},
"environment": {
"image": "aws/codebuild/standard:5.0",
"privileged-mode": false,
"compute-type": "BUILD_GENERAL1_SMALL",
"type": "LINUX_CONTAINER",
"environment-variables": []
},
"timeout-in-minutes": 60,
"build-complete": true,
"initiator": "MyCodeBuildDemoUser",
"build-start-time": "Sep 1, 2017 4:12:29 PM",
"source": {
"location": "codebuild-123456789012-input-bucket/my-input-artifact.zip",
"type": "S3"
},
"logs": {
"group-name": "/aws/codebuild/my-sample-project",
"stream-name": "8745a7a9-c340-456a-9166-edf953571bEX",
"deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX"
},
"phases": [
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:12:29 PM",
"duration-in-seconds": 0,
"phase-type": "SUBMITTED",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:13:05 PM",
"duration-in-seconds": 36,
"phase-type": "PROVISIONING",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:05 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 4,
"phase-type": "DOWNLOAD_SOURCE",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "INSTALL",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "PRE_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 70,
"phase-type": "BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "POST_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "UPLOAD_ARTIFACTS",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:26 PM",
"duration-in-seconds": 4,
"phase-type": "FINALIZING",
"phase-status": "SUCCEEDED"
},
{
"start-time": "Sep 1, 2017 4:14:26 PM",
"phase-type": "COMPLETED"
}
]
},
"current-phase": "COMPLETED",
"current-phase-context": "[]",
"version": "1"
}
}
```
Build phase change notifications use the following format:
```
{
"version": "0",
"id": "43ddc2bd-af76-9ca5-2dc7-b695e15adeEX",
"detail-type": "CodeBuild Build Phase Change",
"source": "aws.codebuild",
"account": "123456789012",
"time": "2017-09-01T16:14:21Z",
"region": "us-west-2",
"resources":[
"arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX"
],
"detail":{
"completed-phase": "COMPLETED",
"project-name": "my-sample-project",
"build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX",
"completed-phase-context": "[]",
"additional-information": {
"artifact": {
"md5sum": "da9c44c8a9a3cd4b443126e823168fEX",
"sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX",
"location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip"
},
"environment": {
"image": "aws/codebuild/standard:5.0",
"privileged-mode": false,
"compute-type": "BUILD_GENERAL1_SMALL",
"type": "LINUX_CONTAINER",
"environment-variables": []
},
"timeout-in-minutes": 60,
"build-complete": true,
"initiator": "MyCodeBuildDemoUser",
"build-start-time": "Sep 1, 2017 4:12:29 PM",
"source": {
"location": "codebuild-123456789012-input-bucket/my-input-artifact.zip",
"type": "S3"
},
"logs": {
"group-name": "/aws/codebuild/my-sample-project",
"stream-name": "8745a7a9-c340-456a-9166-edf953571bEX",
"deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX"
},
"phases": [
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:12:29 PM",
"duration-in-seconds": 0,
"phase-type": "SUBMITTED",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:12:29 PM",
"end-time": "Sep 1, 2017 4:13:05 PM",
"duration-in-seconds": 36,
"phase-type": "PROVISIONING",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:05 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 4,
"phase-type": "DOWNLOAD_SOURCE",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "INSTALL",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:13:10 PM",
"duration-in-seconds": 0,
"phase-type": "PRE_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:13:10 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 70,
"phase-type": "BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "POST_BUILD",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:21 PM",
"duration-in-seconds": 0,
"phase-type": "UPLOAD_ARTIFACTS",
"phase-status": "SUCCEEDED"
},
{
"phase-context": [],
"start-time": "Sep 1, 2017 4:14:21 PM",
"end-time": "Sep 1, 2017 4:14:26 PM",
"duration-in-seconds": 4,
"phase-type": "FINALIZING",
"phase-status": "SUCCEEDED"
},
{
"start-time": "Sep 1, 2017 4:14:26 PM",
"phase-type": "COMPLETED"
}
]
},
"completed-phase-status": "SUCCEEDED",
"completed-phase-duration-seconds": 4,
"version": "1",
"completed-phase-start": "Sep 1, 2017 4:14:21 PM",
"completed-phase-end": "Sep 1, 2017 4:14:26 PM"
}
}
```
# Build badges sample with CodeBuild
AWS CodeBuild now supports the use of build badges, which provide an embeddable, dynamically generated image (*badge*) that displays the status of the latest build for a project. This image is accessible through a publicly available URL generated for your CodeBuild project. This allows anyone to view the status of a CodeBuild project. Build badges do not contain any security information, so they do not require authentication.
**Topics**
+ [Create a build project with build badges](#sample-build-badges-request-running)
+ [Access AWS CodeBuild build badges](access-badges.md)
+ [Publish CodeBuild build badges](publish-badges.md)
+ [CodeBuild badge statuses](badge-statuses.md)
## Create a build project with build badges
Use the following one of the following procedures to create a build project with build badges enabled. You can use AWS CLI or the AWS Management Console.
**To create a build project with build badges enabled (AWS CLI)**
+ For information about creating a build project, see [Create a build project (AWS CLI)](create-project.md#create-project-cli). To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true`.
**To create a build project with build badges enabled (console)**
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**.
1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.
1. In **Source**, for **Source provider**, choose the source code provider type, and then do one of the following:
**Note**
CodeBuild does not support build badges with the Amazon S3 source provider. Because AWS CodePipeline uses Amazon S3 for artifact transfers, build badges are not supported for build projects that are part of a pipeline created in CodePipeline.
+ If you chose **CodeCommit**, then for **Repository**, choose the name of the repository. Select **Enable build badge** to make your project's build status visible and embeddable.
+ 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. Select **Enable build badge** to make your project's build status visible and embeddable.
+ 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. Select **Enable build badge** to make your project's build status visible and embeddable.
**Important**
Updating your project source might affect the accuracy of the project's build badges.
1. In **Environment**:
For **Environment image**, do one of the following:
+ To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime(s)**, **Image**, and **Image version**. Make a selection from **Environment type** if it is available.
+ To use another Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account.
+ To use a private Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image. The credentials must be created by Secrets Manager. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*.
1. In **Service role**, do one of the following:
+ If you do not have a CodeBuild service role, choose **New service role**. In **Role name**, enter a name for the new role.
+ If you have a CodeBuild service role, choose **Existing service role**. In **Role ARN**, choose the service role.
**Note**
When you use the console to create or update a build project, you can create a 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.
1. In **Buildspec**, do one of the following:
+ Choose **Use a buildspec file** to use the buildspec.yml file in the source code root directory.
+ Choose **Insert build commands** to use the console to insert build commands.
For more information, see the [Buildspec reference](build-spec-ref.md).
1. In **Artifacts**, for **Type**, do one of the following:
+ If you do not want to create build output artifacts, choose **No artifacts**.
+ To store the build output in an 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 **Name** blank. Otherwise, enter the name. By default, the artifact name is the project name. If you want to use a different name, enter it in the artifacts name box. If you want to output a ZIP file, include the zip extension.
+ For **Bucket name**, choose the name of the output bucket.
+ If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter 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 [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax).
1. Expand **Additional configuration** and choose options as appropriate.
1. Choose **Create build project**. On the **Review** page, choose **Start build** to run the build.
# Access AWS CodeBuild build badges
You can use AWS CodeBuild console or the AWS CLI to access build badges.
+ In the CodeBuild console, in the list of build projects, in the **Name** column, choose the link that corresponds to the build project. On the **Build project: *project-name*** page, in **Configuration**, choose **Copy badge URL**. For more information, see [View a build project's details (console)](view-project-details.md#view-project-details-console).
+ In the AWS CLI, run the `batch-get-projects` command. The build badge URL is included in the project environment details section of the output. For more information, see [View a build project's details (AWS CLI)](view-project-details.md#view-project-details-cli).
The build badge request URL is generated with a common default branch, but you can specify any branch in your source repository that you have used to run a build. For example:
```
https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch=
```
You can also specify a tag from your source repository by substituting the `branch` parameter with the `tag` parameter in the badge URL. For example:
```
https://codebuild.us-east-1.amazon.com/badges?uuid=...&tag=
```
# Publish CodeBuild build badges
You can display the status of the latest build in a markdown file using your build badge URL in a markdown image. This is useful to display the status of the most recent build in the readme.md file in your source repository (for example, GitHub or CodeCommit). For example:
```
![]()
```
# CodeBuild badge statuses
The CodeBuild build badge can have one of the following statuses.
+ **PASSING** The most recent build on the given branch passed.
+ **FAILING** The most recent build on the given branch timed out, failed, faulted, or was stopped.
+ **IN\$1PROGRESS** The most recent build on the given branch is in progress.
+ **UNKNOWN** The project has not yet run a build for the given branch or at all. Also, the build badges feature might have been disabled.
# 'Test report using the AWS CLI' sample
Tests that you specify in your buildspec file are run during your build. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild. You can use JUnit to create unit tests, or you can use another tool to create configuration tests. You can then evaluate the test results to fix issues or optimize your application.
You can use the CodeBuild API or the AWS CodeBuild console to access the test results. This sample shows you how to configure your report so its test results are exported to an S3 bucket.
**Topics**
+ [Run the test report sample](#sample-test-report-cli-run)
## Run the test report sample
Use the following steps to run the trest report sample.
**Topics**
+ [Prerequisites](#sample-test-report-cli-prerequisites)
+ [Step 1: Create a report group](#sample-test-report-cli-create-report)
+ [Step 2: Configure a project with a report group](#sample-test-report-cli-create-project-with-report)
+ [Step 3: Run and view results of a report](#sample-test-report-cli-run-and-view-report-results)
### Prerequisites
+ Create your test cases. This sample is written with the assumption that you have test cases to include in your sample test report. You specify the location of your test files in the buildspec file.
The following test report file formats are supported:
+ Cucumber JSON (.json)
+ JUnit XML (.xml)
+ NUnit XML (.xml)
+ NUnit3 XML (.xml)
+ TestNG XML (.xml)
+ Visual Studio TRX (.trx)
+ Visual Studio TRX XML (.xml)
Create your test cases with any test framework that can create report files in one of these formats (for example, Surefire JUnit plugin, TestNG, or Cucumber).
+ Create an S3 bucket and make a note of its name. For more information, see [How do I create an S3 bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon S3 User Guide*.
+ Create an IAM role and make a note of its ARN. You need the ARN when you create your build project.
+ If your role does not have the following permissions, add them.
```
{
"Effect": "Allow",
"Resource": [
"*"
],
"Action": [
"codebuild:CreateReportGroup",
"codebuild:CreateReport",
"codebuild:UpdateReport",
"codebuild:BatchPutTestCases"
]
}
```
For more information, see [Permissions for test reporting operations](test-permissions.md#test-permissions-related-to-reporting).
### Step 1: Create a report group
1. Create a file named `CreateReportGroupInput.json`.
1. Create a folder in your S3 bucket where your test results are exported.
1. Copy the following into `CreateReportGroupInput.json`. For ``, use the name of the S3 bucket. For ``, enter the path to the folder in your S3 bucket.
```
{
"name": "",
"type": "TEST",
"exportConfig": {
"exportConfigType": "S3",
"s3Destination": {
"bucket": "",
"path": "",
"packaging": "NONE"
}
}
}
```
1. Run the following command in the directory that contains `CreateReportGroupInput.json`.
```
aws codebuild create-report-group --cli-input-json file://CreateReportGroupInput.json
```
The output looks like the following. Make a note of the ARN for the `reportGroup`. You use it when you create a project that uses this report group.
```
{
"reportGroup": {
"arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/",
"name": "",
"type": "TEST",
"exportConfig": {
"exportConfigType": "S3",
"s3Destination": {
"bucket": "",
"path": "",
"packaging": "NONE",
"encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3"
}
},
"created": 1570837165.885,
"lastModified": 1570837165.885
}
}
```
### Step 2: Configure a project with a report group
To run a report, you first create a CodeBuild build project that is configured with your report group. Test cases specified for your report group are run when you run a build.
1. Create a buildspec file named `buildspec.yml`.
1. Use the following YAML as a template for your `buildspec.yml` file. Be sure to include the commands that run your tests. In the `reports` section, specify the files that contain the results of your test cases. These files store the test results you can access with CodeBuild. They expire 30 days after they are created. These files are different from the raw test case result files you export to an S3 bucket.
```
version: 0.2
phases:
install:
runtime-versions:
java: openjdk8
build:
commands:
- echo Running tests
-
reports:
: #test file information
files:
- ''
base-directory: ''
discard-paths: false #do not remove file paths from test result files
```
**Note**
Instead of the ARN of an existing report group, you can also specify a name for a report group that has not been created. If you specify a name instead of an ARN, CodeBuild creates a report group when it runs a build. Its name contains your project name and the name you specify in the buildspec file, in this format: `project-name-report-group-name`. For more information, see [Create test reports](report-create.md) and [Report group naming](test-report-group-naming.md).
1. Create a file named `project.json`. This file contains input for the **create-project** command.
1. Copy the following JSON into `project.json`. For `source`, enter the type and location of the repository that contains your source files. For `serviceRole`, specify the ARN of the role you are using.
```
{
"name": "test-report-project",
"description": "sample-test-report-project",
"source": {
"type": "CODECOMMIT|CODEPIPELINE|GITHUB|S3|BITBUCKET|GITHUB_ENTERPRISE|NO_SOURCE",
"location": ""
},
"artifacts": {
"type": "NO_ARTIFACTS"
},
"cache": {
"type": "NO_CACHE"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/standard:5.0",
"computeType": "small"
},
"serviceRole": "arn:aws:iam:::role/service-role/"
}
```
1. Run the following command in the directory that contains `project.json`. This creates a project named `test-project`.
```
aws codebuild create-project --cli-input-json file://project.json
```
### Step 3: Run and view results of a report
In this section, you run a build of the project you created earlier. During the build process, CodeBuild creates a report with the results of the test cases. The report is contained in the report group you specified.
1. To start a build, run the following command. `test-report-project` is the name of the build project created above. Make a note of the build ID that appears in the output.
```
aws codebuild start-build --project-name test-report-project
```
1. Run the following command to get information about your build, including the ARN of your report. For ``, specify your build ID. Make a note of the report ARN in the `reportArns` property of the output.
```
aws codebuild batch-get-builds --ids
```
1. Run the following command to get details about your report. For ``, specify your report ARN.
```
aws codebuild batch-get-reports --report-arns
```
The output looks like the following. This sample output shows how many of the tests were successful, failed, skipped, resulted in an error, or return an unknown status.
```
{
"reports": [
{
"status": "FAILED",
"reportGroupArn": "",
"name": "",
"created": 1573324770.154,
"exportConfig": {
"exportConfigType": "S3",
"s3Destination": {
"bucket": "",
"path": "",
"packaging": "NONE",
"encryptionKey": ""
}
},
"expired": 1575916770.0,
"truncated": false,
"executionId": "arn:aws:codebuild:us-west-2:123456789012:build/:2c254862-ddf6-4831-a53f-6839a73829c1",
"type": "TEST",
"arn": "",
"testSummary": {
"durationInNanoSeconds": 6657770,
"total": 11,
"statusCounts": {
"FAILED": 3,
"SKIPPED": 7,
"ERROR": 0,
"SUCCEEDED": 1,
"UNKNOWN": 0
}
}
}
],
"reportsNotFound": []
}
```
1. Run the following command to list information about test cases for your report. For ``, specify the ARN of your report. For the optional `--filter` parameter, you can specify one status result (`SUCCEEDED`, `FAILED`, `SKIPPED`, `ERROR`, or `UNKNOWN`).
```
aws codebuild describe-test-cases \
--report-arn \
--filter status=SUCCEEDED|FAILED|SKIPPED|ERROR|UNKNOWN
```
The output looks like the following.
```
{
"testCases": [
{
"status": "FAILED",
"name": "Test case 1",
"expired": 1575916770.0,
"reportArn": "",
"prefix": "Cucumber tests for agent",
"message": "A test message",
"durationInNanoSeconds": 1540540,
"testRawDataPath": ""
},
{
"status": "SUCCEEDED",
"name": "Test case 2",
"expired": 1575916770.0,
"reportArn": "",
"prefix": "Cucumber tests for agent",
"message": "A test message",
"durationInNanoSeconds": 1540540,
"testRawDataPath": ""
}
]
}
```
# Docker samples for CodeBuild
This section describes sample integrations between Docker and AWS CodeBuild.
| Sample | Description |
| --- | --- |
| [Docker in custom image sample for CodeBuild](sample-docker-custom-image.md) | This sample builds and runs a Docker image by using CodeBuild and a custom Docker build image (`docker:dind` in Docker Hub). |
| [Docker image build server sample for CodeBuild](sample-docker-server.md) | This sample offloads your Docker builds to a managed image build server. |
| [Windows Docker builds sample for CodeBuild](sample-windows-docker-custom-image.md) | This sample builds and runs a Windows Docker image by using CodeBuild. |
| ['Publish Docker image to an Amazon ECR image repository' sample for CodeBuild](sample-docker.md) | This sample produces as build output a Docker image and then pushes the Docker image to an Amazon Elastic Container Registry (Amazon ECR) image repository. |
| [Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md) | This sample shows you how to use a Docker image that is stored in a private registry as your CodeBuild runtime environment. |
# Docker in custom image sample for CodeBuild
The following sample builds and runs a Docker image by using AWS CodeBuild and a custom Docker build image (`docker:dind` in Docker Hub).
To learn how to build a Docker image by using a build image provided by CodeBuild with Docker support instead, see our ['Publish Docker image to Amazon ECR' sample](sample-docker.md).
**Important**
Running this sample might result in charges to your AWS account. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, and CloudWatch Logs. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), and [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing).
**Topics**
+ [Run the Docker in custom image sample](#sample-docker-custom-image-running)
## Run the Docker in custom image sample
Use the following procedure to run the Docker in custom image sample. For more information about this sample, see [Docker in custom image sample for CodeBuild](#sample-docker-custom-image).
**To run the Docker in custom image sample**
1. Create the files as described in the [Directory structure](#sample-docker-custom-image-dir) and [Files](#sample-docker-custom-image-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Create a build project, run the build, and view related build information.
If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "sample-docker-custom-image-project",
"source": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-input-bucket/DockerCustomImageSample.zip"
},
"artifacts": {
"type": "NO_ARTIFACTS"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "docker:dind",
"computeType": "BUILD_GENERAL1_SMALL",
"privilegedMode": false
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
**Note**
By default, Docker daemon is enabled for non-VPC builds. If you would like to use Docker containers for VPC builds, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website and enable privileged mode. Also, Windows does not support privileged mode.
1. To see the build results, look in the build's log for the string `Hello, World!`. For more information, see [View build details](view-build-details.md).
### Directory structure
This sample assumes this directory structure.
```
(root directory name)
├── buildspec.yml
└── Dockerfile
```
### Files
The base image of the operating system used in this sample is Ubuntu. The sample uses these files.
`buildspec.yml` (in `(root directory name)`)
```
version: 0.2
phases:
pre_build:
commands:
- docker build -t helloworld .
build:
commands:
- docker images
- docker run helloworld echo "Hello, World!"
```
`Dockerfile` (in `(root directory name)`)
```
FROM maven:3.3.9-jdk-8
RUN echo "Hello World"
```
# Docker image build server sample for CodeBuild
The following sample offloads your Docker builds to a managed image build server. You can adapt this sample to provision a dedicated and managed Docker image build server in your CodeBuild project configuration. Note that the provisioned instance is active while builds are actively run for the project, and the instance is stopped when builds are not running. The provisioned instance is stored for up to a month before it is recycled. For more information, see [ CodeBuild Docker Server Capability](https://aws.amazon.com/blogs//aws/accelerate-ci-cd-pipelines-with-the-new-aws-codebuild-docker-server-capability).
**Important**
Running this sample might result in charges to your AWS account. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, and CloudWatch Logs. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), and [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing).
**Topics**
+ [Configure a Docker server](#sample-docker-server-running)
## Configure a Docker server
Use the following procedure to provision a dedicated compute environment for a CodeBuild project that manages Docker workloads and stores Docker image layers.
**To configure a Docker server**
1. Create the files as described in the [Directory structure](#sample-docker-server-dir) and [Files](#sample-docker-server-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Create a build project, run the build, and view related build information:
1. In the **Environment** section of the console, choose **Additional configuration**, navigate to **Docker server configuration**, and then select **Enable docker server for this project**. You can then choose the **Docker server compute type** and supply a **Registry credential**.
1. If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "sample-docker-custom-image-project",
"source": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-input-bucket/DockerServerSample.zip"
},
"artifacts": {
"type": "NO_ARTIFACTS"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/amazonlinux-x86_64-standard:5.0",
"computeType": "BUILD_GENERAL1_LARGE",
"dockerServer": [
{
"computeType": "BUILD_GENERAL1_LARGE",
"securityGroupIds": [ "security-groups-ID" ]
}
]
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name"
}
```
**Note**
Security groups configured for Docker servers should allow ingress network traffic from the VPC configured in the project. They should allow ingress on port 9876.
1. To see the build results, look in the build's log for the string `Hello, World!`. For more information, see [View build details](view-build-details.md).
### Directory structure
This sample assumes this directory structure.
```
(root directory name)
├── buildspec.yml
└── Dockerfile
```
### Files
The base image of the operating system used in this sample is Ubuntu. The sample uses these files.
`buildspec.yml` (in `(root directory name)`)
```
version: 0.2
phases:
build:
commands:
- docker buildx build -t helloworld --load .
- docker run helloworld echo "Hello, World!"
```
`Dockerfile` (in `(root directory name)`)
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN echo "Hello World"
```
# Windows Docker builds sample for CodeBuild
The following sample builds and runs a Windows Docker image by using CodeBuild.
**Topics**
+ [Run Windows Docker builds sample](#sample-windows-docker-build-running)
## Run Windows Docker builds sample
Use the following procedure to run the Windows Docker builds.
**To run Windows Docker builds sample**
1. Create the files as described in the [Directory structure](#sample-windows-docker-custom-image-dir) and [Files](#sample-windows-docker-custom-image-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Create a `WINDOWS_EC2` fleet.
If you use the AWS CLI to create the fleet, the JSON-formatted input to the `create-fleet` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "fleet-name",
"baseCapacity": 1,
"environmentType": "WINDOWS_EC2",
"computeType": "BUILD_GENERAL1_MEDIUM"
}
```
1. Create a build project, run the build, and view related build information.
If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "project-name",
"source": {
"type": "S3",
"location": "bucket-name/DockerImageSample.zip"
},
"artifacts": {
"type": "NO_ARTIFACTS"
},
"environment": {
"type": "WINDOWS_EC2",
"image": "Windows",
"computeType": "BUILD_GENERAL1_MEDIUM",
"fleet": {
"fleetArn": "fleet-arn"
}
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name"
}
```
1. To see the build results, look in the build's log for the string `Hello, World!`. For more information, see [View build details](view-build-details.md).
### Directory structure
This sample assumes this directory structure.
```
(root directory name)
├── buildspec.yml
└── Dockerfile
```
### Files
The base image of the operating system used in this sample is `mcr.microsoft.com/windows/servercore:ltsc2022`. The sample uses these files.
`buildspec.yml` (in `(root directory name)`)
```
version: 0.2
phases:
pre_build:
commands:
- docker build -t helloworld .
build:
commands:
- docker images
- docker run helloworld powershell -Command "Write-Host 'Hello World!'"
```
`Dockerfile` (in `(root directory name)`)
```
FROM mcr.microsoft.com/windows/servercore:ltsc2022
RUN powershell -Command "Write-Host 'Hello World'"
```
# 'Publish Docker image to an Amazon ECR image repository' sample for CodeBuild
This sample produces as build output a Docker image and then pushes the Docker image to an Amazon Elastic Container Registry (Amazon ECR) image repository. You can adapt this sample to push the Docker image to Docker Hub. For more information, see [Adapt the 'Publish Docker image to Amazon ECR' sample to push to Docker Hub](sample-docker-docker-hub.md).
To learn how to build a Docker image by using a custom Docker build image (`docker:dind` in Docker Hub), see our [Docker in custom image sample](sample-docker-custom-image.md).
This sample was tested referencing `golang:1.12`.
This sample uses the new multi-stage Docker builds feature, which produces a Docker image as build output. It then pushes the Docker image to an Amazon ECR image repository. Multi-stage Docker image builds help to reduce the size of the final Docker image. For more information, see [Use multi-stage builds with Docker](https://docs.docker.com/engine/userguide/eng-image/multistage-build/).
**Important**
Running this sample might result in charges to your AWS account. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing).
**Topics**
+ [Run the 'Publish Docker image to Amazon ECR' sample](#sample-docker-running)
+ [Adapt the 'Publish Docker image to Amazon ECR' sample to push to Docker Hub](sample-docker-docker-hub.md)
## Run the 'Publish Docker image to Amazon ECR' sample
Use the following procedure to run the sample that publishes a Docker image to Amazon ECR. For more infomration about this sample, see ['Publish Docker image to an Amazon ECR image repository' sample for CodeBuild](#sample-docker).
**To run this sample**
1. If you already have an image repository in Amazon ECR you want to use, skip to step 3. Otherwise, if you are using an user instead of an AWS root account or an administrator user to work with Amazon ECR, add this statement (between *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1* and *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1*) to the user (or IAM group the user is associated with). Using an AWS root account is not recommended.This statement allows the creation of Amazon ECR repositories for storing Docker images. Ellipses (`...`) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the policy. For more information, see [Working with inline policies using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *user Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:CreateRepository"
],
"Resource": "*"
}
]
}
```
------
**Note**
The IAM entity that modifies this policy must have permission in IAM to modify policies.
1. Create an image repository in Amazon ECR. Be sure to create the repository in the same AWS Region where you create your build environment and run your build. For more information, see [Creating a repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*. This repository's name must match the repository name you specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable. Ensure that the Amazon ECR repository policy grants image push access for your CodeBuild service IAM role.
1. Add this statement (between *\$1\$1\$1 BEGIN ADDING STATEMENT HERE \$1\$1\$1* and *\$1\$1\$1 END ADDING STATEMENT HERE \$1\$1\$1*) to the policy you attached to your AWS CodeBuild service role. This statement allows CodeBuild to upload Docker images to Amazon ECR repositories. Ellipses (`...`) are used for brevity and to help you locate where to add the statement. Do not remove any statements, and do not type these ellipses into the policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:CompleteLayerUpload",
"ecr:GetAuthorizationToken",
"ecr:InitiateLayerUpload",
"ecr:PutImage",
"ecr:UploadLayerPart"
],
"Resource": "*"
}
]
}
```
------
**Note**
The IAM entity that modifies this policy must have permission in IAM to modify policies.
1. Create the files as described in the [Directory structure](#sample-docker-dir) and [Files](#sample-docker-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository. For more information, see [ Image definitions file reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/file-reference.html) in the *AWS CodePipeline User Guide*.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Create a build project, run the build, and view build information.
If you use the console to create your project:
1. For **Operating system**, choose **Ubuntu**.
1. For **Runtime**, choose **Standard**.
1. For **Image**, choose **aws/codebuild/standard:5.0**.
1. Add the following environment variables:
+ AWS\$1DEFAULT\$1REGION with a value of *region-ID*
+ AWS\$1ACCOUNT\$1ID with a value of *account-ID*
+ IMAGE\$1TAG with a value of Latest
+ IMAGE\$1REPO\$1NAME with a value of *Amazon-ECR-repo-name*
If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to this. (Replace the placeholders with your own values.)
```
{
"name": "sample-docker-project",
"source": {
"type": "S3",
"location": "codebuild-region-ID-account-ID-input-bucket/DockerSample.zip"
},
"artifacts": {
"type": "NO_ARTIFACTS"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/standard:5.0",
"computeType": "BUILD_GENERAL1_SMALL",
"environmentVariables": [
{
"name": "AWS_DEFAULT_REGION",
"value": "region-ID"
},
{
"name": "AWS_ACCOUNT_ID",
"value": "account-ID"
},
{
"name": "IMAGE_REPO_NAME",
"value": "Amazon-ECR-repo-name"
},
{
"name": "IMAGE_TAG",
"value": "latest"
}
],
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
1. Confirm that CodeBuild successfully pushed the Docker image to the repository:
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. Choose the repository name. The image should be listed in the **Image tag** column.
### Directory structure
This sample assumes this directory structure.
```
(root directory name)
├── buildspec.yml
└── Dockerfile
```
### Files
This sample uses these files.
`buildspec.yml` (in `(root directory name)`)
```
version: 0.2
phases:
pre_build:
commands:
- echo Logging in to Amazon ECR...
- aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
build:
commands:
- echo Build started on `date`
- echo Building the Docker image...
- docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .
- docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
post_build:
commands:
- echo Build completed on `date`
- echo Pushing the Docker image...
- docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
```
`Dockerfile` (in `(root directory name)`)
```
FROM golang:1.12-alpine AS build
#Install git
RUN apk add --no-cache git
#Get the hello world package from a GitHub repository
RUN go get github.com/golang/example/hello
WORKDIR /go/src/github.com/golang/example/hello
# Build the project and send the output to /bin/HelloWorld
RUN go build -o /bin/HelloWorld
FROM golang:1.12-alpine
#Copy the build's output binary from the previous build container
COPY --from=build /bin/HelloWorld /bin/HelloWorld
ENTRYPOINT ["/bin/HelloWorld"]
```
**Note**
CodeBuild overrides the `ENTRYPOINT` for custom Docker images.
# Adapt the 'Publish Docker image to Amazon ECR' sample to push to Docker Hub
To adapt the 'Publish Docker image to Amazon ECR' sample so that the Docker image is pushed to Docker Hub instead of Amazon ECR, edit the sample's code. For more information about the sample, see ['Publish Docker image to an Amazon ECR image repository' sample for CodeBuild](sample-docker.md) and [Run the 'Publish Docker image to Amazon ECR' sample](sample-docker.md#sample-docker-running).
**Note**
If you are using a version of Docker earlier than 17.06, remove the `--no-include-email` option.
1. Replace these Amazon ECR-specific lines of code in the `buildspec.yml` file:
```
...
pre_build:
commands:
- echo Logging in to Amazon ECR...
- aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
build:
commands:
- echo Build started on `date`
- echo Building the Docker image...
- docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .
- docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
post_build:
commands:
- echo Build completed on `date`
- echo Pushing the Docker image...
- docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
...
```
With these Docker Hub-specific lines of code:
```
...
pre_build:
commands:
- echo Logging in to Docker Hub...
# Type the command to log in to your Docker Hub account here.
build:
commands:
- echo Build started on `date`
- echo Building the Docker image...
- docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .
- docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $IMAGE_REPO_NAME:$IMAGE_TAG
post_build:
commands:
- echo Build completed on `date`
- echo Pushing the Docker image...
- docker push $IMAGE_REPO_NAME:$IMAGE_TAG
...
```
1. Upload the edited code to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)`, just the files inside of `(root directory name)`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`.
1. Replace these lines of code from the JSON-formatted input to the `create-project` command:
```
...
"environmentVariables": [
{
"name": "AWS_DEFAULT_REGION",
"value": "region-ID"
},
{
"name": "AWS_ACCOUNT_ID",
"value": "account-ID"
},
{
"name": "IMAGE_REPO_NAME",
"value": "Amazon-ECR-repo-name"
},
{
"name": "IMAGE_TAG",
"value": "latest"
}
]
...
```
With these lines of code:
```
...
"environmentVariables": [
{
"name": "IMAGE_REPO_NAME",
"value": "your-Docker-Hub-repo-name"
},
{
"name": "IMAGE_TAG",
"value": "latest"
}
]
...
```
1. Create a build environment, run the build, and view related build information.
1. Confirm that AWS CodeBuild successfully pushed the Docker image to the repository. Sign in to Docker Hub, go to the repository, and choose the **Tags** tab. The `latest` tag should contain a very recent **Last Updated** value.
# Private registry with AWS Secrets Manager sample for CodeBuild
This sample shows you how to use a Docker image that is stored in a private registry as your AWS CodeBuild runtime environment. The credentials for the private registry are stored in AWS Secrets Manager. Any private registry works with CodeBuild. This sample uses Docker Hub.
**Note**
Secrets are visible to actions and are not masked when written to a file.
**Topics**
+ [Private registry sample requirements](#sample-private-registry-requirements)
+ [Create a CodeBuild project with a private registry](private-registry-sample-create-project.md)
+ [Configure a private registry credential for self-hosted runners](private-registry-sample-configure-runners.md)
## Private registry sample requirements
To use a private registry with AWS CodeBuild, you must have the following:
+ A Secrets Manager secret that stores your Docker Hub credentials. The credentials are used to access your private repository.
**Note**
You will be charged for secrets that you create.
+ A private repository or account.
+ A CodeBuild service role IAM policy that grants access to your Secrets Manager secret.
Follow these steps to create these resources and then create a CodeBuild build project using the Docker images stored in your private registry.
# Create a CodeBuild project with a private registry
1. For information about how to create a free private repository, see [Repositories on Docker Hub](https://docs.docker.com/docker-hub/repos/). You can also run the following commands in a terminal to pull an image, get its ID, and push it to a new repository.
```
docker pull amazonlinux
docker images amazonlinux --format {{.ID}}
docker tag image-id your-username/repository-name:tag
docker login
docker push your-username/repository-name
```
1. Follow the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *AWS Secrets Manager User Guide*.
1. In step 3, in **Choose secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create one key-value pair for your Docker Hub user name and one key-value pair for your Docker Hub password.
1. Continue following the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
1. In step 5, on the **Configure automatic rotation** page, turn it off because the keys correspond to your Docker Hub credentials.
1. Finish following the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)
1. When you create an AWS CodeBuild project in the console, CodeBuild attaches the required permission for you. If you use an AWS KMS key other than `DefaultEncryptionKey`, you must add it to the service role. For more information, see [Modifying a role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html#roles-managingrole-editing-console) in the *IAM User Guide*.
For your service role to work with Secrets Manager, it must have, at a minimum, the `secretsmanager:GetSecretValue` permission.
![\[The service role configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/private-registry-sample-iam.png)
1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project. For information, see [Create a build project (console)](create-project.md#create-project-console).
**Note**
If your private registry is in your VPC, it must have public internet access. CodeBuild cannot pull an image from a private IP address in a VPC.
1. In **Environment image**, choose **Custom image**.
1. For **Environment type**, choose **Linux** or **Windows**.
1. For **Image registry**, choose **Other registry**.
1. In **External registry URL**, enter the image location and in **Registry credential - optional** enter the ARN or name of your Secrets Manager credentials.
**Note**
If your credentials do not exist in your current Region, then you must use the ARN. You cannot use the credential name if the credentials exist in a different Region.
# Configure a private registry credential for self-hosted runners
Use the following instructions to configure a registry credential for a self-hosted runner.
**Note**
Note that these credentials will only be used if the images are overridden with those from private registries.
------
#### [ AWS Management Console ]
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project or select an existing project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Change a build project's settings (console)](change-project.md#change-project-console).
1. In **Environment**, choose **Additional configuration**.
1. In **Additional configuration**, enter the name or ARN of the secret from AWS Secrets Manager for **Registry credential - optional**.
![\[The registry credential configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/registry-credential.png)
------
#### [ AWS CLI ]
1. If you'd like to create a new project, run the **create-project** command.
```
aws codebuild create-project \
--name project-name \
--source type=source-type,location=source-location \
--environment "type=environment-type,image=image,computeType=compute-type,registryCredential={credentialProvider=SECRETS_MANAGER,credential=secret-name-or-arn},imagePullCredentialsType=CODEBUILD|SERVICE_ROLE" \
--artifacts type=artifacts-type \
--service-role arn:aws:iam::account-ID:role/service-role/service-role-name
```
1. If you'd like to update an existing project, run the **update-project** command.
```
aws codebuild update-project \
--name project-name \
--environment "type=environment-type,image=image,computeType=compute-type,registryCredential={credentialProvider=SECRETS_MANAGER,credential=secret-name-or-arn}"
```
------
# Create a static website with build output hosted in an S3 bucket
You can disable the encryption of artifacts in a build. You might want to do this so that you can publish artifacts to a location that is configured to host a website. (You cannot publish encrypted artifacts.) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an S3 bucket that is configured to be a website.
1. Follow the instructions in [Setting up a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HostingWebsiteOnS3Setup.html) to configure an S3 bucket to function like a website.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**.
1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.
1. In **Source**, for **Source provider**, choose **GitHub**. Follow the instructions to connect (or reconnect) with GitHub, and then choose **Authorize**.
For **Webhook**, select **Rebuild every time a code change is pushed to this repository**. You can select this check box only if you chose **Use a repository in my account**.
![\[The webhook configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/webhook.png)
1. In **Environment**:
For **Environment image**, do one of the following:
+ To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime(s)**, **Image**, and **Image version**. Make a selection from **Environment type** if it is available.
+ To use another Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account.
+ To use a private Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image. The credentials must be created by Secrets Manager. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*.
1. In **Service role**, do one of the following:
+ If you do not have a CodeBuild service role, choose **New service role**. In **Role name**, enter a name for the new role.
+ If you have a CodeBuild service role, choose **Existing service role**. In **Role ARN**, choose the service role.
**Note**
When you use the console to create or update a build project, you can create a 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.
1. In **Buildspec**, do one of the following:
+ Choose **Use a buildspec file** to use the buildspec.yml file in the source code root directory.
+ Choose **Insert build commands** to use the console to insert build commands.
For more information, see the [Buildspec reference](build-spec-ref.md).
1. In **Artifacts**, for ** Type**, choose **Amazon S3** to store the build output in an S3 bucket.
1. For **Bucket name**, choose the name of the S3 bucket you configured to function as a website in step 1.
1. If you chose **Insert build commands** in **Environment**, then for **Output files**, enter the locations of the files from the build that you want to put into the output bucket. If you have more than one location, use a comma to separate each location (for example, **appspec.yml, target/my-app.jar**). For more information, see [Artifacts reference-key in the buildspec file](build-spec-ref.md#artifacts-build-spec).
1. Select **Disable artifacts encryption**.
1. Expand **Additional configuration** and choose options as appropriate.
1. Choose **Create build project**. On the build project page, in **Build history**, choose **Start build** to run the build.
1. (Optional) Follow the instructions in [Example: Speed up your website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/userguide/website-hosting-cloudfront-walkthrough.html) in the *Amazon S3 Developer Guide*.
# Multiple input sources and output artifacts sample
You can create an AWS CodeBuild build project with more than one input source and more than one set of output artifacts. This sample shows you how to set up a build project that:
+ Uses multiple sources and repositories of varying types.
+ Publishes build artifacts to multiple S3 buckets in a single build.
In the following sample, you create a build project and use it to run a build. The sample uses the build project's buildspec file to show you how to incorporate more than one source and create more than one set of artifacts.
To learn how to to create a pipeline that uses multiple source inputs to CodeBuild to create multiple output artifacts, see [Sample of a CodePipeline/CodeBuild integration with multiple input sources and output artifacts](sample-codepipeline.md#sample-pipeline-multi-input-output).
**Topics**
+ [Create a build project with multiple inputs and outputs](sample-multi-in-out-create.md)
+ [Create a build project without a source](no-source.md)
# Create a build project with multiple inputs and outputs
Use the following procedure to create a build project with multiple inputs and outputs.
**To create a build project with multiple inputs and outputs**
1. Upload your sources to one or more S3 buckets, CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repositories.
1. Choose which source is the primary source. This is the source in which CodeBuild looks for and runs your buildspec file.
1. Create a build project. For more information, see [Create a build project in AWS CodeBuild](create-project.md).
1. Create your build project, run the build, and get information about the build.
1. If you use the AWS CLI to create the build project, the JSON-formatted input to the `create-project` command might look similar to the following:
```
{
"name": "sample-project",
"source": {
"type": "S3",
"location": ""
},
"secondarySources": [
{
"type": "CODECOMMIT",
"location": "https://git-codecommit.us-west-2.amazonaws.com/v1/repos/repo",
"sourceIdentifier": "source1"
},
{
"type": "GITHUB",
"location": "https://github.com/awslabs/aws-codebuild-jenkins-plugin",
"sourceIdentifier": "source2"
}
],
"secondaryArtifacts": [ss
{
"type": "S3",
"location": "",
"artifactIdentifier": "artifact1"
},
{
"type": "S3",
"location": "",
"artifactIdentifier": "artifact2"
}
],
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/standard:5.0",
"computeType": "BUILD_GENERAL1_SMALL"
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
Your primary source is defined under the `source` attribute. All other sources are called secondary sources and appear under `secondarySources`. All secondary sources are installed in their own directory. This directory is stored in the built-in environment variable `CODEBUILD_SRC_DIR_sourceIdentifer`. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md).
The `secondaryArtifacts` attribute contains a list of artifact definitions. These artifacts use the `secondary-artifacts` block of the buildspec file that is nested inside the `artifacts` block.
Secondary artifacts in the buildspec file have the same structure as artifacts and are separated by their artifact identifier.
**Note**
In the [CodeBuild API](https://docs.aws.amazon.com/codebuild/latest/APIReference/), the `artifactIdentifier` on a secondary artifact is a required attribute in `CreateProject` and `UpdateProject`. It must be used to reference a secondary artifact.
Using the preceding JSON-formatted input, the buildspec file for the project might look like:
```
version: 0.2
phases:
install:
runtime-versions:
java: openjdk11
build:
commands:
- cd $CODEBUILD_SRC_DIR_source1
- touch file1
- cd $CODEBUILD_SRC_DIR_source2
- touch file2
artifacts:
files:
- '**.*'
secondary-artifacts:
artifact1:
base-directory: $CODEBUILD_SRC_DIR_source1
files:
- file1
artifact2:
base-directory: $CODEBUILD_SRC_DIR_source2
files:
- file2
```
You can override the version of the primary source using the API with the `sourceVersion` attribute in `StartBuild`. To override one or more secondary source versions, use the `secondarySourceVersionOverride` attribute.
The JSON-formatted input to the the `start-build` command in the AWS CLI might look like:
```
{
"projectName": "sample-project",
"secondarySourcesVersionOverride": [
{
"sourceIdentifier": "source1",
"sourceVersion": "codecommit-branch"
},
{
"sourceIdentifier": "source2",
"sourceVersion": "github-branch"
},
]
}
```
# Create a build project without a source
You can configure a CodeBuild project by choosing the **NO\$1SOURCE** source type when you configure your source. When your source type is **NO\$1SOURCE**, you cannot specify a buildspec file because your project does not have a source. Instead, you must specify a YAML-formatted buildspec string in the `buildspec` attribute of the JSON-formatted input to the `create-project` CLI command. It might look like this:
```
{
"name": "project-name",
"source": {
"type": "NO_SOURCE",
"buildspec": "version: 0.2\n\nphases:\n build:\n commands:\n - command"
},
"environment": {
"type": "LINUX_CONTAINER",
"image": "aws/codebuild/standard:5.0",
"computeType": "BUILD_GENERAL1_SMALL",
},
"serviceRole": "arn:aws:iam::account-ID:role/role-name",
"encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID"
}
```
For more information, see [Create a build project (AWS CLI)](create-project.md#create-project-cli).
# Runtime versions in buildspec file sample for CodeBuild
If you use the Amazon Linux 2 (AL2) standard image version 1.0 or later, or the Ubuntu standard image version 2.0 or later, you can specify one or more runtimes in the `runtime-versions` section of your buildspec file. The following samples show how you can change your project runtime, specify more than one runtime, and specify a runtime that is dependent on another runtime. For information about supported runtimes, see [Docker images provided by CodeBuild](build-env-ref-available.md).
**Note**
If you use Docker in your build container, your build must run in privileged mode. For more information, see [Run AWS CodeBuild builds manually](run-build.md) and [Create a build project in AWS CodeBuild](create-project.md).
**Topics**
+ [Update the runtime version in the buildspec file](sample-runtime-update-version.md)
+ [Specify two runtimes](sample-runtime-two-major-version-runtimes.md)
# Update the runtime version in the buildspec file
You can modify the runtime used by your project to a new version by updating the `runtime-versions` section of your buildspec file. The following examples show how to specify java versions 8 and 11.
+ A `runtime-versions` section that specifies version 8 of Java:
```
phases:
install:
runtime-versions:
java: corretto8
```
+ A `runtime-versions` section that specifies version 11 of Java:
```
phases:
install:
runtime-versions:
java: corretto11
```
The following examples show how to specify different versions of Python using the Ubuntu standard image 5.0 or the Amazon Linux 2 standard image 3.0:
+ A `runtime-versions` section that specifies Python version 3.7:
```
phases:
install:
runtime-versions:
python: 3.7
```
+ A `runtime-versions` section that specifies Python version 3.8:
```
phases:
install:
runtime-versions:
python: 3.8
```
This sample demonstrates a project that starts with the Java version 8 runtime, and then is updated to the Java version 10 runtime.
1. Download and install Maven. For information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html) on the Apache Maven website.
1. Switch to an empty directory on your local computer or instance, and then run this Maven command.
```
mvn archetype:generate "-DgroupId=com.mycompany.app" "-DartifactId=ROOT" "-DarchetypeArtifactId=maven-archetype-webapp" "-DinteractiveMode=false"
```
If successful, this directory structure and files are created.
```
.
└── ROOT
├── pom.xml
└── src
└── main
├── resources
└── webapp
├── WEB-INF
│ └── web.xml
└── index.jsp
```
1. Create a file named `buildspec.yml` with the following contents. Store the file in the ` (root directory name)/my-web-app` directory.
```
version: 0.2
phases:
install:
runtime-versions:
java: corretto8
build:
commands:
- java -version
- mvn package
artifacts:
files:
- '**/*'
base-directory: 'target/my-web-app'
```
In the buildspec file:
+ The `runtime-versions` section specifies that the project uses version 8 of the Java runtime.
+ The `- java -version` command displays the version of Java used by your project when it builds.
Your file structure should now look like this.
```
(root directory name)
└── my-web-app
├── src
│ ├── main
│ ├── resources
│ └── webapp
│ └── WEB-INF
│ └── web.xml
│ └── index.jsp
├── buildspec.yml
└── pom.xml
```
1. Upload the contents of the `my-web-app` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository.
**Important**
Do not upload `(root directory name)` or `(root directory name)/my-web-app`, just the directories and files in `(root directory name)/my-web-app`.
If you are using an S3 input bucket, be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket. Do not add `(root directory name)` or `(root directory name)/my-web-app` to the ZIP file, just the directories and files in `(root directory name)/my-web-app`.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). Leave all settings at their default values, except for these settings.
+ For **Environment**:
+ For **Environment image**, choose **Managed image**.
+ For **Operating system**, choose **Amazon Linux 2**.
+ For **Runtime(s)**, choose **Standard**.
+ For **Image**, choose **aws/codebuild/amazonlinux-x86\$164-standard:4.0**.
1. Choose **Start build**.
1. On **Build configuration**, accept the defaults, and then choose **Start build**.
1. After the build is complete, view the build output on the **Build logs** tab. You should see output similar to the following:
```
[Container] Date Time Phase is DOWNLOAD_SOURCE
[Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src
[Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml
[Container] Date Time Processing environment variables
[Container] Date Time Selecting 'java' runtime version 'corretto8' based on manual selections...
[Container] Date Time Running command echo "Installing Java version 8 ..."
Installing Java version 8 ...
[Container] Date Time Running command export JAVA_HOME="$JAVA_8_HOME"
[Container] Date Time Running command export JRE_HOME="$JRE_8_HOME"
[Container] Date Time Running command export JDK_HOME="$JDK_8_HOME"
[Container] Date Time Running command for tool_path in "$JAVA_8_HOME"/bin/* "$JRE_8_HOME"/bin/*;
```
1. Update the `runtime-versions` section with Java version 11:
```
install:
runtime-versions:
java: corretto11
```
1. After you save the change, run your build again and view the build output. You should see that the installed version of Java is 11. You should see output similar to the following:
```
[Container] Date Time Phase is DOWNLOAD_SOURCE
[Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src
[Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml
[Container] Date Time Processing environment variables
[Container] Date Time Selecting 'java' runtime version 'corretto11' based on manual selections...
Installing Java version 11 ...
[Container] Date Time Running command export JAVA_HOME="$JAVA_11_HOME"
[Container] Date Time Running command export JRE_HOME="$JRE_11_HOME"
[Container] Date Time Running command export JDK_HOME="$JDK_11_HOME"
[Container] Date Time Running command for tool_path in "$JAVA_11_HOME"/bin/* "$JRE_11_HOME"/bin/*;
```
# Specify two runtimes
You can specify more than one runtime in the same CodeBuild build project. This sample project uses two source files: one that uses the Go runtime and one that uses the Node.js runtime.
1. Create a directory named `my-source`.
1. Inside the `my-source` directory, create a directory named `golang-app`.
1. Create a file named `hello.go` with the following contents. Store the file in the `golang-app` directory.
```
package main
import "fmt"
func main() {
fmt.Println("hello world from golang")
fmt.Println("1+1 =", 1+1)
fmt.Println("7.0/3.0 =", 7.0/3.0)
fmt.Println(true && false)
fmt.Println(true || false)
fmt.Println(!true)
fmt.Println("good bye from golang")
}
```
1. Inside the `my-source` directory, create a directory named `nodejs-app`. It should be at the same level as the `golang-app` directory.
1. Create a file named `index.js` with the following contents. Store the file in the `nodejs-app` directory.
```
console.log("hello world from nodejs");
console.log("1+1 =" + (1+1));
console.log("7.0/3.0 =" + 7.0/3.0);
console.log(true && false);
console.log(true || false);
console.log(!true);
console.log("good bye from nodejs");
```
1. Create a file named `package.json` with the following contents. Store the file in the `nodejs-app` directory.
```
{
"name": "mycompany-app",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"run some tests here\""
},
"author": "",
"license": "ISC"
}
```
1. Create a file named `buildspec.yml` with the following contents. Store the file in the `my-source` directory, at the same level as the `nodejs-app` and `golang-app` directories. The `runtime-versions` section specifies the Node.js version 12 and Go version 1.13 runtimes.
```
version: 0.2
phases:
install:
runtime-versions:
golang: 1.13
nodejs: 12
build:
commands:
- echo Building the Go code...
- cd $CODEBUILD_SRC_DIR/golang-app
- go build hello.go
- echo Building the Node code...
- cd $CODEBUILD_SRC_DIR/nodejs-app
- npm run test
artifacts:
secondary-artifacts:
golang_artifacts:
base-directory: golang-app
files:
- hello
nodejs_artifacts:
base-directory: nodejs-app
files:
- index.js
- package.json
```
1. Your file structure should now look like this.
```
my-source
├── golang-app
│ └── hello.go
├── nodejs.app
│ ├── index.js
│ └── package.json
└── buildspec.yml
```
1. Upload the contents of the `my-source` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository.
**Important**
If you are using an S3 input bucket, be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket. Do not add `my-source` to the ZIP file, just the directories and files in `my-source`.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). Leave all settings at their default values, except for these settings.
+ For **Environment**:
+ For **Environment image**, choose **Managed image**.
+ For **Operating system**, choose **Amazon Linux 2**.
+ For **Runtime(s)**, choose **Standard**.
+ For **Image**, choose **aws/codebuild/amazonlinux-x86\$164-standard:4.0**.
1. Choose **Create build project**.
1. Choose **Start build**.
1. On **Build configuration**, accept the defaults, and then choose **Start build**.
1. After the build is complete, view the build output on the **Build logs** tab. You should see output similar to the following. It shows output from the Go and Node.js runtimes. It also shows output from the Go and Node.js applications.
```
[Container] Date Time Processing environment variables
[Container] Date Time Selecting 'golang' runtime version '1.13' based on manual selections...
[Container] Date Time Selecting 'nodejs' runtime version '12' based on manual selections...
[Container] Date Time Running command echo "Installing Go version 1.13 ..."
Installing Go version 1.13 ...
[Container] Date Time Running command echo "Installing Node.js version 12 ..."
Installing Node.js version 12 ...
[Container] Date Time Running command n $NODE_12_VERSION
installed : v12.20.1 (with npm 6.14.10)
[Container] Date Time Moving to directory /codebuild/output/src819694850/src
[Container] Date Time Registering with agent
[Container] Date Time Phases found in YAML: 2
[Container] Date Time INSTALL: 0 commands
[Container] Date Time BUILD: 1 commands
[Container] Date Time Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED
[Container] Date Time Phase context status code: Message:
[Container] Date Time Entering phase INSTALL
[Container] Date Time Phase complete: INSTALL State: SUCCEEDED
[Container] Date Time Phase context status code: Message:
[Container] Date Time Entering phase PRE_BUILD
[Container] Date Time Phase complete: PRE_BUILD State: SUCCEEDED
[Container] Date Time Phase context status code: Message:
[Container] Date Time Entering phase BUILD
[Container] Date Time Running command echo Building the Go code...
Building the Go code...
[Container] Date Time Running command cd $CODEBUILD_SRC_DIR/golang-app
[Container] Date Time Running command go build hello.go
[Container] Date Time Running command echo Building the Node code...
Building the Node code...
[Container] Date Time Running command cd $CODEBUILD_SRC_DIR/nodejs-app
[Container] Date Time Running command npm run test
> mycompany-app@1.0.0 test /codebuild/output/src924084119/src/nodejs-app
> echo "run some tests here"
run some tests here
```
# Source version sample with AWS CodeBuild
This sample demonstrates how to specify a version of your source using a format other than a commit ID (also known as a commit SHA). You can specify the version of your source in the following ways:
+ For an Amazon S3 source provider, use the version ID of the object that represents the build input ZIP file.
+ For CodeCommit, Bitbucket, GitHub, and GitHub Enterprise Server, use one of the following:
+ Pull request as a pull request reference (for example, `refs/pull/1/head`).
+ Branch as a branch name.
+ Commit ID.
+ Tag.
+ Reference and a commit ID. The reference can be one of the following:
+ A tag (for example, `refs/tags/mytagv1.0^{full-commit-SHA}`).
+ A branch (for example, `refs/heads/mydevbranch^{full-commit-SHA}`).
+ A pull request (for example, `refs/pull/1/head^{full-commit-SHA}`).
+ For GitLab and GitLab Self Managed, use one of the following:
+ Branch as a branch name.
+ Commit ID.
+ Tag.
**Note**
You can specify the version of a pull request source only if your repository is GitHub or GitHub Enterprise Server.
If you use a reference and a commit ID to specify a version, the `DOWNLOAD_SOURCE` phase of your build is faster than if you provide the version only. This is because when you add a reference, CodeBuild does not need to download the entire repository to find the commit.
+ You can specify a source version with only a commit ID, such as `12345678901234567890123467890123456789`. If you do this, CodeBuild must download the entire repository to find the version.
+ You can specify a source version with a reference and a commit ID in this format: `refs/heads/branchname^{full-commit-SHA}` (for example, `refs/heads/main^{12345678901234567890123467890123456789}`). If you do this, CodeBuild downloads only the specified branch to find the version. .
**Note**
To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git clone depth** to a low number. CodeBuild downloads fewer versions of your repository.
**Topics**
+ [Specify a GitHub repository version with a commit ID](sample-source-version-github.md)
+ [Specify a GitHub repository version with a reference and commit ID](sample-source-version-github-ref.md)
# Specify a GitHub repository version with a commit ID
You can specify a source version with only a commit ID, such as `12345678901234567890123467890123456789`. If you do this, CodeBuild must download the entire repository to find the version.
**To specify a GitHub repository version with a commit ID**
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). Leave all settings at their default values, except for these settings:
+ In **Source**:
+ For **Source provider**, choose **GitHub**. If you are not connected to GitHub, follow the instructions to connect.
+ For **Repository**, choose **Public repository**.
+ For **Repository URL**, enter **https://github.com/aws/aws-sdk-ruby.git**.
+ In **Environment**:
+ For **Environment image**, choose **Managed image**.
+ For **Operating system**, choose **Amazon Linux 2**.
+ For **Runtime(s)**, choose **Standard**.
+ For **Image**, choose **aws/codebuild/amazonlinux-x86\$164-standard:4.0**.
1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**.
1. In **Build commands**, replace the placeholder text with the following:
```
version: 0.2
phases:
install:
runtime-versions:
ruby: 2.6
build:
commands:
- echo $CODEBUILD_RESOLVED_SOURCE_VERSION
```
The `runtime-versions` section is required when you use the Ubuntu standard image 2.0. Here, the Ruby version 2.6 runtime is specified, but you can use any runtime. The `echo` command displays the version of the source code stored in the `CODEBUILD_RESOLVED_SOURCE_VERSION` environment variable.
1. On **Build configuration**, accept the defaults, and then choose **Start build**.
1. For **Source version**, enter **046e8b67481d53bdc86c3f6affdd5d1afae6d369**. This is the SHA of a commit in the `https://github.com/aws/aws-sdk-ruby.git` repository.
1. Choose **Start build**.
1. When the build is complete, you should see the following:
+ On the **Build logs** tab, which version of the project source was used. Here is an example.
```
[Container] Date Time Running command echo $CODEBUILD_RESOLVED_SOURCE_VERSION
046e8b67481d53bdc86c3f6affdd5d1afae6d369
[Container] Date Time Phase complete: BUILD State: SUCCEEDED
```
+ On the **Environment variables** tab, the **Resolved source version** matches the commit ID used to create the build.
+ On the **Phase details** tab, the duration of the `DOWNLOAD_SOURCE` phase.
# Specify a GitHub repository version with a reference and commit ID
You can specify a source version with a reference and a commit ID in this format: `refs/heads/branchname^{full-commit-SHA}` (for example, `refs/heads/main^{12345678901234567890123467890123456789}`). If you do this, CodeBuild downloads only the specified branch to find the version.
**To specify a GitHub repository version with a reference and commit ID.**
1. Complete the steps in [Specify a GitHub repository version with a commit ID](sample-source-version-github.md).
1. From the left navigation pane, choose **Build projects**, and then choose the project you created earlier.
1. Choose **Start build**.
1. In **Source version**, enter **refs/heads/main^\$1046e8b67481d53bdc86c3f6affdd5d1afae6d369\$1**. This is the same commit ID and a reference to a branch in the format `refs/heads/branchname^{full-commit-SHA}`.
1. Choose **Start build**.
1. When the build is complete, you should see the following:
+ On the **Build logs** tab, which version of the project source was used. Here is an example.
```
[Container] Date Time Running command echo $CODEBUILD_RESOLVED_SOURCE_VERSION
046e8b67481d53bdc86c3f6affdd5d1afae6d369
[Container] Date Time Phase complete: BUILD State: SUCCEEDED
```
+ On the **Environment variables** tab, the **Resolved source version** matches the commit ID used to create the build.
+ On the **Phase details** tab, the duration of the `DOWNLOAD_SOURCE` phase should be shorter than the duration when you used only the commit ID to specify the version of your source.
# Third-party source repository samples for CodeBuild
This section describes sample integrations between third-party source repositories and CodeBuild.
| Sample | Description |
| --- | --- |
| BitBucket pull request and webhook filter sample – see [Run the 'Bitbucket pull request and webhook filter' sample for CodeBuild](sample-bitbucket-pull-request.md) | This sample shows you how to create a pull request using a Bitbucket repository. It also shows you how to use a Bitbucket webhook to trigger CodeBuild to create a build of a project. |
| GitHub Enterprise Server sample – see [Run the GitHub Enterprise Server sample for CodeBuild](sample-github-enterprise.md) | This sample shows you how to set up your CodeBuild projects when your GitHub Enterprise Server repository has a certificate installed. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise Server repository. |
| GitHub pull request and webhook filter sample – see [Run the GitHub pull request and webhook filter sample for CodeBuild](sample-github-pull-request.md) | This sample shows you how to create a pull request using a GitHub Enterprise Server repository. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise Server repository. |
# Run the 'Bitbucket pull request and webhook filter' sample for CodeBuild
AWS CodeBuild supports webhooks when the source repository is Bitbucket. This means that for a CodeBuild build project that has its source code stored in a Bitbucket repository, webhooks can be used to rebuild the source code every time a code change is pushed to the repository. For more information, see [Bitbucket webhook events](bitbucket-webhook.md).
This sample shows you how to create a pull request using a Bitbucket repository. It also shows you how to use a Bitbucket webhook to trigger CodeBuild to create a build of a project.
**Note**
When using webhooks, it is possible for a user to trigger an unexpected build. To mitigate this risk, see [Best practices for using webhooks](webhooks.md#webhook-best-practices).
**Topics**
+ [Prerequisites](#sample-bitbucket-pull-request-prerequisites)
+ [Step 1: Create a build project with Bitbucket and enable webhooks](#sample-bitbucket-pull-request-create)
+ [Step 2: Trigger a build with a Bitbucket webhook](#sample-bitbucket-pull-request-trigger)
## Prerequisites
To run this sample you must connect your AWS CodeBuild project with your Bitbucket account.
**Note**
CodeBuild has updated its permissions with Bitbucket. If you previously connected your project to Bitbucket and now receive a Bitbucket connection error, you must reconnect to grant CodeBuild permission to manage your webhooks.
## Step 1: Create a build project with Bitbucket and enable webhooks
The following steps describe how to create an AWS CodeBuild project with Bitbucket as a source repository and enable webhooks.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**.
1. Choose **Create build project**.
1. In **Project configuration**:
**Project name**
Enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.
1. In **Source**:
**Source provider**
Choose **Bitbucket**. Follow the instructions to connect (or reconnect) with Bitbucket and then choose **Authorize**.
**Repository**
Choose **Repository in my Bitbucket account**.
If you have not previously connected to your Bitbucket account, enter your Bitbucket username and app password, and select **Save Bitbucket credentials**.
**Bitbucket repository**
Enter the URL for your Bitbucket repository.
1. In **Primary source webhook events**, select the following.
**Note**
The **Primary source webhook events** section is only visible if you chose **Repository in my Bitbucket account** in the previous step.
1. Select **Rebuild every time a code change is pushed to this repository** when you create your project.
1. From **Event type**, choose one or more events.
1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters.
1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters.
1. Choose **Add filter group** to add another filter group, if needed.
For more information about Bitbucket webhook event types and filters, see [Bitbucket webhook events](bitbucket-webhook.md).
1. In **Environment**:
**Environment image**
Choose one of the following:
To use a Docker image managed by AWS CodeBuild:
Choose **Managed image**, and then make selections from **Operating system**, **Runtime(s)**, **Image**, and **Image version**. Make a selection from **Environment type** if it is available.
To use another Docker image:
Choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account.
To use a private Docker image:
Choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image. The credentials must be created by Secrets Manager. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*.
**Service role**
Choose one of the following:
+ If you do not have a CodeBuild service role, choose **New service role**. In **Role name**, enter a name for the new role.
+ If you have a CodeBuild service role, choose **Existing service role**. In **Role ARN**, choose the service role.
When you use the console to create or update a build project, you can create a 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.
1. In **Buildspec**, do one of the following:
+ Choose **Use a buildspec file** to use the buildspec.yml file in the source code root directory.
+ Choose **Insert build commands** to use the console to insert build commands.
For more information, see the [Buildspec reference](build-spec-ref.md).
1. In **Artifacts**:
**Type**
Choose one of the following:
+ If you do not want to create build output artifacts, choose **No artifacts**.
+ To store the build output in an 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 **Name** blank. Otherwise, enter the name. By default, the artifact name is the project name. If you want to use a different name, enter it in the artifacts name box. If you want to output a ZIP file, include the zip extension.
+ For **Bucket name**, choose the name of the output bucket.
+ If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter 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 [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax).
**Additional configuration**
Expand **Additional configuration** and set options as appropriate.
1. Choose **Create build project**. On the **Review** page, choose **Start build** to run the build.
## Step 2: Trigger a build with a Bitbucket webhook
For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code.
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. On the navigation pane, choose **Build projects**, and then choose a project associated with a Bitbucket repository with webhooks. For information about creating a Bitbucket webhook project, see [Step 1: Create a build project with Bitbucket and enable webhooks](#sample-bitbucket-pull-request-create).
1. Make some changes in the code in your project's Bitbucket repository.
1. Create a pull request on your Bitbucket repository. For more information, see [Making a pull request](https://www.atlassian.com/git/tutorials/making-a-pull-request).
1. On the Bitbucket webhooks page, choose **View request** to see a list of recent events.
1. Choose **View details** to see details about the response returned by CodeBuild. It might look something like this:
```
"response":"Webhook received and build started: https://us-east-1.console.aws.amazon.com/codebuild/home..."
"statusCode":200
```
1. Navigate to the Bitbucket pull request page to see the status of the build.
# Run the GitHub Enterprise Server sample for CodeBuild
AWS CodeBuild supports GitHub Enterprise Server as a source repository. This sample shows how to set up your CodeBuild projects when your GitHub Enterprise Server repository has a certificate installed. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise Server repository.
**Topics**
+ [Prerequisites](#sample-github-enterprise-prerequisites)
+ [Step 1: Create a build project with GitHub Enterprise Server and enable webhooks](#sample-github-enterprise-running)
## Prerequisites
1. Generate a personal access token for your CodeBuild project. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user. Copy it to your clipboard so that it can be used when you create your CodeBuild project. For more information, see [Creating a personal access token for the command line](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) on the GitHub Help website.
When you create the personal access token, include the **repo** scope in the definition.
![\[The repo scope in the definition.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png)
1. Download your certificate from GitHub Enterprise Server. CodeBuild uses the certificate to make a trusted SSL connection to the repository.
**Linux/macOS clients:**
From a terminal window, run the following command:
```
echo -n | openssl s_client -connect HOST:PORTNUMBER \
| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /folder/filename.pem
```
Replace the placeholders in the command with the following values:
*HOST*. The IP address of your GitHub Enterprise Server repository.
*PORTNUMBER*. The port number you are using to connect (for example, 443).
*folder*. The folder where you downloaded your certificate.
*filename*. The file name of your certificate file.
**Important**
Save the certificate as a .pem file.
**Windows clients:**
Use your browser to download your certificate from GitHub Enterprise Server. To see the site's certificate details, choose the padlock icon. For information about how to export the certificate, see your browser documentation.
**Important**
Save the certificate as a .pem file.
1. Upload your certificate file to an S3 bucket. For information about how to create an S3 bucket, see [How do I create an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket.html) For information about how to upload objects to an S3 bucket, see [How do I upload files and folders to a bucket?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)
**Note**
This bucket 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, the bucket must be in the US East (Ohio) Region.
## Step 1: Create a build project with GitHub Enterprise Server and enable webhooks
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**.
1. In **Project name**, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.
1. In **Source**, in **Source provider**, choose **GitHub Enterprise Server**.
+ Choose **Manage account credentials**, and then choose **Personal access token**. For **Service**, choose **Secrets Manager (recommended)**, and configure your secret. Then in **,GitHub Enterprise personal access token**, enter your personal access token and choose **Save**.
+ In **Repository URL**, enter the path to your repository, including the name of the repository.
+ Expand **Additional configuration**.
+ Select **Rebuild every time a code change is pushed to this repository** to rebuild every time a code change is pushed to this repository.
+ Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise Server project repository.
**Note**
We recommend that you use **Enable insecure SSL** for testing only. It should not be used in a production environment.
![\[The GitHub Enterprise Server project repository configuration.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png)
1. In **Environment**:
For **Environment image**, do one of the following:
+ To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime(s)**, **Image**, and **Image version**. Make a selection from **Environment type** if it is available.
+ To use another Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account.
+ To use a private Docker image, choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image. The credentials must be created by Secrets Manager. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*.
1. In **Service role**, do one of the following:
+ If you do not have a CodeBuild service role, choose **New service role**. In **Role name**, enter a name for the new role.
+ If you have a CodeBuild service role, choose **Existing service role**. In **Role ARN**, choose the service role.
**Note**
When you use the console to create or update a build project, you can create a 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.
1. Expand **Additional configuration**.
If you want CodeBuild to work with your VPC:
+ For **VPC**, choose the VPC ID that CodeBuild uses.
+ For **VPC Subnets**, choose the subnets that include resources that CodeBuild uses.
+ For **VPC Security groups**, choose the security groups that CodeBuild uses to allow access to resources in the VPCs.
For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md).
1. In **Buildspec**, do one of the following:
+ Choose **Use a buildspec file** to use the buildspec.yml file in the source code root directory.
+ Choose **Insert build commands** to use the console to insert build commands.
For more information, see the [Buildspec reference](build-spec-ref.md).
1. In **Artifacts**, for **Type**, do one of the following:
+ If you do not want to create build output artifacts, choose **No artifacts**.
+ To store the build output in an 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 **Name** blank. Otherwise, enter the name. By default, the artifact name is the project name. If you want to use a different name, enter it in the artifacts name box. If you want to output a ZIP file, include the zip extension.
+ For **Bucket name**, choose the name of the output bucket.
+ If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter 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 [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax).
1. For **Cache type**, choose one of the following:
+ If you do not want to use a cache, choose **No cache**.
+ If you want to use an Amazon S3 cache, choose **Amazon S3**, and then do the following:
+ For **Bucket**, choose the name of the S3 bucket where the cache is stored.
+ (Optional) For **Cache path prefix**, enter an Amazon S3 path prefix. The **Cache path prefix** value is similar to a directory name. It makes it possible for you to store the cache under the same directory in a bucket.
**Important**
Do not append a trailing slash (/) to the end of the path prefix.
+ If you want to use a local cache, choose **Local**, and then choose one or more local cache modes.
**Note**
Docker layer cache mode is available for Linux only. If you choose it, your project must run in privileged mode.
Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax). For more information about caching, see [Cache builds to improve performance](build-caching.md).
1. Choose **Create build project**. On the build project page, choose **Start build**.
# Run the GitHub pull request and webhook filter sample for CodeBuild
AWS CodeBuild supports webhooks when the source repository is GitHub. This means that for a CodeBuild build project that has its source code stored in a GitHub repository, webhooks can be used to rebuild the source code every time a code change is pushed to the repository. For CodeBuild samples, see [AWS CodeBuild Samples](https://github.com/aws-samples/aws-codebuild-samples).
**Note**
When using webhooks, it is possible for a user to trigger an unexpected build. To mitigate this risk, see [Best practices for using webhooks](webhooks.md#webhook-best-practices).
**Topics**
+ [Step 1: Create a build project with GitHub and enable webhooks](#sample-github-pull-request-running)
+ [Step 2: Verify that webhooks are enabled](#verification-checks)
## Step 1: Create a build project with GitHub and enable webhooks
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. If a CodeBuild information page is displayed, choose **Create build project**. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**.
1. Choose **Create build project**.
1. In **Project configuration**:
**Project name**
Enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.
1. In **Source**:
**Source provider**
Choose **GitHub**. Follow the instructions to connect (or reconnect) with GitHub and then choose **Authorize**.
**Repository**
Choose **Repository in my GitHub account**.
**GitHub repository**
Enter the URL for your GitHub repository.
1. In **Primary source webhook events**, select the following.
**Note**
The **Primary source webhook events** section is only visible if you chose **Repository in my GitHub account** in the previous step.
1. Select **Rebuild every time a code change is pushed to this repository** when you create your project.
1. From **Event type**, choose one or more events.
1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters.
1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters.
1. Choose **Add filter group** to add another filter group, if needed.
For more information about GitHub webhook event types and filters, see [GitHub webhook events](github-webhook.md).
1. In **Environment**:
**Environment image**
Choose one of the following:
To use a Docker image managed by AWS CodeBuild:
Choose **Managed image**, and then make selections from **Operating system**, **Runtime(s)**, **Image**, and **Image version**. Make a selection from **Environment type** if it is available.
To use another Docker image:
Choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account.
To use a private Docker image:
Choose **Custom image**. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image. The credentials must be created by Secrets Manager. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*.
**Service role**
Choose one of the following:
+ If you do not have a CodeBuild service role, choose **New service role**. In **Role name**, enter a name for the new role.
+ If you have a CodeBuild service role, choose **Existing service role**. In **Role ARN**, choose the service role.
When you use the console to create or update a build project, you can create a 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.
1. In **Buildspec**, do one of the following:
+ Choose **Use a buildspec file** to use the buildspec.yml file in the source code root directory.
+ Choose **Insert build commands** to use the console to insert build commands.
For more information, see the [Buildspec reference](build-spec-ref.md).
1. In **Artifacts**:
**Type**
Choose one of the following:
+ If you do not want to create build output artifacts, choose **No artifacts**.
+ To store the build output in an 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 **Name** blank. Otherwise, enter the name. By default, the artifact name is the project name. If you want to use a different name, enter it in the artifacts name box. If you want to output a ZIP file, include the zip extension.
+ For **Bucket name**, choose the name of the output bucket.
+ If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter 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 [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax).
**Additional configuration**
Expand **Additional configuration** and set options as appropriate.
1. Choose **Create build project**. On the **Review** page, choose **Start build** to run the build.
## Step 2: Verify that webhooks are enabled
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. In the navigation pane, choose **Build projects**.
1. Do one of the following:
+ Choose the link for the build project with webhooks you want to verify, and then choose **Build details**.
+ Choose the button next to the build project with webhooks you want to verify, choose **View details**, and then choose the **Build details** tab.
1. In **Primary source webhook events**, choose the **Webhook** URL link.
1. In your GitHub repository, on the **Settings** page, under **Webhooks**, verify that **Pull Requests** and **Pushes** are selected.
1. In your GitHub profile settings, under **Personal settings**, **Applications**, **Authorized OAuth Apps**, you should see that your application has been authorized to access the AWS Region you selected.
# Tutorial: Apple code signing with Fastlane in CodeBuild using S3 for certificate storage
[fastlane](https://docs.fastlane.tools/) is a popular open source automation tool to automate beta deployments and releases for your iOS and Android apps. It handles all tedious tasks, like generating screenshots, dealing with code signing, and releasing your application.
## Prerequisites
To complete this tutorial, you must first have set up the following:
+ An AWS account
+ An [ Apple Developer account ](https://developer.apple.com/)
+ An S3 bucket for storing certificates
+ fastlane installed in your project - [ Guide ](https://docs.fastlane.tools/getting-started/ios/setup/) to install fastlane
## Step 1: Set up Fastlane Match with S3 on your local machine
[Fastlane Match](https://docs.fastlane.tools/actions/match/) is one of the [ Fastlane tools](https://fastlane.tools/), and it allows for seamless configuration for code signing in both your local development environment and on CodeBuild. Fastlane Match stores all of your code signing certificates and provisioning profiles in a Git repository/S3 Bucket/Google Cloud Storage, and downloads and installs the necessary certificates and profiles when required.
In this example configuration, you will set up and use an Amazon S3 bucket for storage.
****
1. Initialize match in your project:
```
fastlane match init
```
1. When prompted, choose S3 as the storage mode.
1. Update your `*Matchfile*` to use S3:
```
storage_mode("s3")
s3_bucket("your-s3-bucket-name")
s3_region("your-aws-region")
type("appstore") # The default type, can be: appstore, adhoc, enterprise or development
```
## Step 2: Set up your Fastfile
Create or update your `Fastfile` with the following lane.
On CodeBuild, Fastlane Match will need to be run every time you build and sign your app. The easiest way to do this is to add the `match` action to the lane which builds your app.
```
default_platform(:ios)
platform :ios do
before_all do
setup_ci
end
desc "Build and sign the app"
lane :build do
match(type: "appstore", readonly: true)
gym(
scheme: "YourScheme",
export_method: "app-store"
)
end
end
```
**Note**
Make sure to add `setup_ci` to the `before_all `section in `Fastfile` for the match action to work correctly. This ensures that a temporary Fastlane keychain with the appropriate permissions is used. Without using this you may see build failures or inconsistent results.
## Step 3: Run the `fastlane match` command to generate respective certificates and profiles
The fastlane match command for the given type (i.e., development, appstore, adhoc, enterprise) will generate the certificate and profile if not available in remote store. The certificates and profiles will be stored in S3 by fastlane.
```
bundle exec fastlane match appstore
```
The command execution will be interactive and fastlane will ask to set pass phrase for decrypting the certificates.
## Step 4: Create the application file for your project
Create or add the application file as appropriate for your project.
****
1. Create or add the [Gymfile](http://docs.fastlane.tools/actions/gym/#gymfile), [Appfile](http://docs.fastlane.tools/advanced/Appfile/), [Snapfile](http://docs.fastlane.tools/actions/snapshot/#snapfile), [Deliverfile](http://docs.fastlane.tools/actions/deliver/#editing-the-deliverfile) based on your project build requirements.
1. Commit the changes to your remote repository
## Step 5: Create environment variables in Secrets Manager
Create two secrets for storing the fastlane session cookie and matching pass phrase. For more information about creating secrets in Secrets Manager, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
****
1. Access your fastlane session cookie as follows.
1. Secret key - `FASTLANE_SESSION`
1. Secret value - session cookie generated from running the following command on your local machine.
**Note**
This value is available after authentication in a local file: `~/.fastlane/spaceship/my_appleid_username/cookie`.
```
fastlane spaceauth -u
```
1. Fastlane Match pass phrase - To enable Fastlane Match to decrypt the certificates and profiles stored in the S3 bucket, it is necessary to add the encryption passphrase that you configured in the Match setup step to the CodeBuild project’s environment variables.
1. Secret key - `MATCH_PASSWORD`
1. Secret value - **. The passphrase is set while generating the certificates in Step 3.
**Note**
While creating the above secrets in Secrets Manager, remember to give a secret name with the following prefix: `/CodeBuild/`
## Step 6: Create a compute fleet
Create the compute fleet for your project.
****
1. In the console, go to CodeBuild and create a new compute fleet.
1. Choose "macOS" as the operating system and select an appropriate compute type and image.
## Step 7: Create a project in CodeBuild
Create your project in CodeBuild.
****
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
1. Set up your source provider (such as GitHub, CodeCommit). This is iOS project source repository and not certificates repository.
1. In **Environment**:
+ Choose **Reserved Capacity**.
+ For **Fleet**, select the fleet created above.
+ Provide the name of the service role that CodeBuild will create for you.
+ Provide the below environment variables.
+ Name: `MATCH_PASSWORD`, Value: **, Type: Secrets Manager (Secrets ARN created in step 5 for MATCH\$1PASSWORD)
+ Name: `FASTLANE_SESSION`, Value: **, Type: Secrets Manager (Secrets ARN created in Step 5 for FASTLANE\$1SESSION)
1. In **Buildspec**, add the following:
```
version: 0.2
phases:
install:
commands:
- gem install bundler
- bundle install
build:
commands:
- echo "Building and signing the app..."
- bundle exec fastlane build
post_build:
commands:
- echo "Build completed on date"
artifacts:
files:
- '*/.ipa'
name: app-$(date +%Y-%m-%d)
```
## Step 8: Configure IAM role
Once the project is created, ensure your CodeBuild project's service role has permissions to access the S3 bucket containing the certificates. Add the following policy to the role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::your-s3-bucket-name"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::your-s3-bucket-name/*"
}
]
}
```
------
## Step 9: Run the build
Run the build. You can review the build status and logs in CodeBuild.
Once the job is completed, you will be able to view the log of the job.
## Troubleshooting
+ If you encounter issues with certificate fetching, ensure your IAM permissions are set up correctly for S3 access.
+ If you encounter issues with certificate decrypting, ensure you set correct passphrase in MATCH\$1PASSWORD environment variable.
+ For code signing issues, verify that your Apple Developer account has the necessary certificates and profiles, and that the bundle identifier in your Xcode project matches the one in your provisioning profile.
## Security considerations
The following are security considerations for this tutorial.
+ Ensure your S3 bucket has appropriate security settings, including encryption at rest. In particular, make sure the bucket has no public access and restrict access to only CodeBuild and the system that needs to have an access.
+ Consider using AWS Secrets Manager for storing sensitive information like the MATCH\$1PASSWORD and FASTLANE\$1SESSION.
This sample provides a setup for iOS code signing with Fastlane in CodeBuild using Amazon S3 for certificate storage. You may need to adjust some steps based on your specific project requirements and CodeBuild environment. This approach leverages AWS services for enhanced security and integration within the AWS ecosystem.
# Tutorial: Apple code signing with Fastlane in CodeBuild using GitHub for certificate storage
[fastlane](https://docs.fastlane.tools/) is a popular open source automation tool to automate beta deployments and releases for your iOS and Android apps. It handles all tedious tasks, like generating screenshots, dealing with code signing, and releasing your application.
This sample demonstrates how to set up Apple code signing using Fastlane in a CodeBuild project running on Mac fleet, with GitHub as the storage for certificates and provisioning profiles.
## Prerequisites
To complete this tutorial, you must first have set up the following:
+ An AWS account
+ An [ Apple Developer account ](https://developer.apple.com/)
+ A private GitHub repository for storing certificates
+ fastlane installed in your project - [ Guide ](https://docs.fastlane.tools/getting-started/ios/setup/) to install fastlane
## Step 1: Set up Fastlane Match with GitHub on your local machine
[Fastlane Match](https://docs.fastlane.tools/actions/match/) is one of the [ Fastlane tools](https://fastlane.tools/), and it allows for seamless configuration for code signing in both your local development environment and on CodeBuild. Fastlane Match stores all of your code signing certificates and provisioning profiles in a Git repository/S3 Bucket/Google Cloud Storage, and downloads and installs the necessary certificates and profiles when required.
In this example configuration, we will set up and use a Git repository for storage.
****
1. Initialize match in your project:
```
fastlane match init
```
1. When prompted, choose GitHub as the storage mode.
1. Update your `*Matchfile*` to use GitHub:
```
git_url("https://github.com/your-username/your-certificate-repo.git")
storage_mode("git")
type("development") # The default type, can be: appstore, adhoc, enterprise or development
```
**Note**
Make sure you enter HTTPS URL for your Git repository for fastlane to successfully authenticate and clone. Otherwise, you may see an authentication error when you attempt to use match.
## Step 2: Set up your Fastfile
Create or update your `Fastfile` with the following lane.
On CodeBuild, Fastlane Match will need to be run every time you build and sign your app. The easiest way to do this is to add the `match` action to the lane which builds your app.
```
default_platform(:ios)
platform :ios do
before_all do
setup_ci
end
desc "Build and sign the app"
lane :build do
match(type: "appstore", readonly: true)
gym(
scheme: "YourScheme",
export_method: "app-store"
)
end
end
```
**Note**
Make sure to add `setup_ci` to the `before_all `section in `Fastfile` for the match action to work correctly. This ensures that a temporary Fastlane keychain with the appropriate permissions is used. Without using this you may see build failures or inconsistent results.
## Step 3: Run the `fastlane match` command to generate respective certificates and profiles
The fastlane match command for the given type (i.e. development, appstore, adhoc, enterprise) will generate the certificate and profile if not available in remote store. The certificates and profiles will be stored in GitHub by fastlane.
```
bundle exec fastlane match appstore
```
The command execution will be interactive and fastlane will ask to set pass phrase for decrypting the certificates.
## Step 4: Create the application file for your project
Create or add the application file as appropriate for your project.
****
1. Create or add the [Gymfile](http://docs.fastlane.tools/actions/gym/#gymfile), [Appfile](http://docs.fastlane.tools/advanced/Appfile/), [Snapfile](http://docs.fastlane.tools/actions/snapshot/#snapfile), [Deliverfile](http://docs.fastlane.tools/actions/deliver/#editing-the-deliverfile) based on your project build requirements.
1. Commit the changes to your remote repository.
## Step 5: Create environment variables in Secrets Manager
Create three secrets for storing the fastlane session cookie and matching pass phrase. For more information about creating secrets in Secrets Manager, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
****
1. Access your fastlane session cookie as follows.
1. Secret key - `FASTLANE_SESSION`
1. Secret value - session cookie generated from running the following command on your local machine.
**Note**
This value is available after authentication in a local file: `~/.fastlane/spaceship/my_appleid_username/cookie`.
```
fastlane spaceauth -u
```
1. Fastlane Match pass phrase - To enable Fastlane Match to decrypt the certificates and profiles stored in the Git repository, it is necessary to add the encryption passphrase that you configured in the Match setup step to the CodeBuild project’s environment variables.
1. Secret key - `MATCH_PASSWORD`
1. Secret value - ``. The passphrase is set while generating the certificates in Step 3.
1. Fastlane `MATCH_GIT_BASIC_AUTHORIZATION` - set a basic authorization for *match*:
1. Secret key:
`MATCH_GIT_BASIC_AUTHORIZATION`
1. Secret value - The value should be a base64 encoded string of your username and personal access token (PAT) in the format `username:password`. You can generate it using the following command:
```
echo -n your_github_username:your_personal_access_token | base64
```
You can generate your PAT on the GitHub console in **Your Profile > Settings > Developers Settings > Personal Access Token**. For more information, see the following guide: [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
**Note**
While creating the above secrets in Secrets Manager, remember to give a secret name with the following prefix: `/CodeBuild/`
## Step 6: Create a compute fleet
Create the compute fleet for your project.
****
1. In the console, go to CodeBuild and create a new compute fleet.
1. Choose `macOS` as the operating system and select an appropriate compute type and image.
## Step 7: Create a project in CodeBuild
Create your project in CodeBuild.
****
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
1. Set up your source provider (such as GitHub, CodeCommit). This is iOS project source repository and not certificates repository.
1. In **Environment**:
+ Choose **Reserved Capacity**.
+ For **Fleet**, select the fleet created above.
+ Provide the name of the service role that CodeBuild will create for you.
+ Provide the below environment variables.
+ Name: `MATCH_PASSWORD`, Value: **, Type: Secrets Manager (Secrets ARN created in step 5 for MATCH\$1PASSWORD)
+ Name: `FASTLANE_SESSION`, Value: **, Type: Secrets Manager (Secrets ARN created in step 5 for FASTLANE\$1SESSION)
+ Name: `MATCH_GIT_BASIC_AUTHORIZATION`, Value: **, Type: Secrets Manager Secrets ARN (created in step 5 for `MATCH_GIT_BASIC_AUTHORIZATION`)
1. In **Buildspec**, add the following:
```
version: 0.2
phases:
install:
commands:
- gem install bundler
- bundle install
build:
commands:
- echo "Building and signing the app..."
- bundle exec fastlane build
post_build:
commands:
- echo "Build completed on date"
artifacts:
files:
- '*/.ipa'
name: app-$(date +%Y-%m-%d)
```
## Step 8: Run the build
Run the build. You can review the build status and logs in CodeBuild.
Once the job is completed, you will be able to view the log of the job.
## Troubleshooting
+ If you encounter issues accessing the GitHub repository, double-check your personal access token and the MATCH\$1GIT\$1BASIC\$1AUTHORIZATION environment variable.
+ If you encounter issues with certificate decrypting, ensure you set correct passphrase in MATCH\$1PASSWORD environment variable.
+ For code signing issues, verify that your Apple Developer account has the necessary certificates and profiles, and that the bundle identifier in your Xcode project matches the one in your provisioning profile.
## Security considerations
The following are security considerations for this tutorial.
+ Keep your GitHub repository for certificates private and regularly audit access.
+ Consider using AWS Secrets Manager for storing sensitive information like the MATCH\$1PASSWORD and FASTLANE\$1SESSION.
This sample provides a setup for iOS code signing with Fastlane in CodeBuild using GitHub for certificate storage. You may need to adjust some steps based on your specific project requirements and CodeBuild environment. This approach leverages AWS services for enhanced security and integration within the AWS ecosystem.
# Set artifact names at build time using semantic versioning
This sample contains example buildspec files that demonstrate how to specify an artifact name that is created at build time. A name specified in a buildspec file can incorporate Shell commands and environment variables to make it unique. A name you specify in a buildspec file overrides a name you enter in the console when you create your project.
If you build multiple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique. For example, you can use a date and timestamp that is inserted into an artifact name at build time.
If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following:
1. Set your build project to override the artifact name with a name in the buildspec file.
+ If you use the console to create your build project, select **Enable semantic versioning**. For more information, see [Create a build project (console)](create-project.md#create-project-console).
+ If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON-formatted file passed to `create-project`. For more information, see [Create a build project (AWS CLI)](create-project.md#create-project-cli).
+ If you use the AWS CodeBuild API, set the `overrideArtifactName` flag on the `ProjectArtifacts` object when a project is created or updated or a build is started.
1. Specify a name in the buildspec file. Use the following sample buildspec files as a guide.
This Linux example shows you how to specify an artifact name that includes the date the build is created:
```
version: 0.2
phases:
build:
commands:
- rspec HelloWorld_spec.rb
artifacts:
files:
- '**/*'
name: myname-$(date +%Y-%m-%d)
```
This Linux example shows you how to specify an artifact name that uses a CodeBuild environment variable. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md).
```
version: 0.2
phases:
build:
commands:
- rspec HelloWorld_spec.rb
artifacts:
files:
- '**/*'
name: myname-$AWS_REGION
```
This Windows example shows you how to specify an artifact name that includes the date and time the build is created:
```
version: 0.2
env:
variables:
TEST_ENV_VARIABLE: myArtifactName
phases:
build:
commands:
- cd samples/helloworld
- dotnet restore
- dotnet run
artifacts:
files:
- '**/*'
name: $Env:TEST_ENV_VARIABLE-$(Get-Date -UFormat "%Y%m%d-%H%M%S")
```
This Windows example shows you how to specify an artifact name that uses a variable declared in the buildspec file and a CodeBuild environment variable. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md).
```
version: 0.2
env:
variables:
TEST_ENV_VARIABLE: myArtifactName
phases:
build:
commands:
- cd samples/helloworld
- dotnet restore
- dotnet run
artifacts:
files:
- '**/*'
name: $Env:TEST_ENV_VARIABLE-$Env:AWS_REGION
```
For more information, see [Build specification reference for CodeBuild](build-spec-ref.md).