AWS CodeBuild Construct Library
AWS CodeBuild is a fully managed continuous integration service that compiles source code, runs tests, and produces software packages that are ready to deploy. With CodeBuild, you don’t need to provision, manage, and scale your own build servers. CodeBuild scales continuously and processes multiple builds concurrently, so your builds are not left waiting in a queue. You can get started quickly by using prepackaged build environments, or you can create custom build environments that use your own build tools. With CodeBuild, you are charged by the minute for the compute resources you use.
Source
Build projects are usually associated with a source, which is specified via the source property which accepts a class that extends the Source abstract base class. The default is to have no source associated with the build project; the buildSpec option is required in that case.
Here's a CodeBuild project with no source which simply prints Hello, CodeBuild!:
ts
new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: [
'echo "Hello, CodeBuild!"',
],
},
},
}),
});
python
codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["echo \"Hello, CodeBuild!\""
]
}
}
})
)
java
Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("echo \"Hello, CodeBuild!\""))))))
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "echo \"Hello, CodeBuild!\"" }
} }
} }
})
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("echo \"Hello, CodeBuild!\""),
},
},
},
}),
})
CodeCommitSource
Use an AWS CodeCommit repository as the source of this build:
ts
import * as codecommit from 'aws-cdk-lib/aws-codecommit';
const repository = new codecommit.Repository(this, 'MyRepo', { repositoryName: 'foo' });
new codebuild.Project(this, 'MyFirstCodeCommitProject', {
source: codebuild.Source.codeCommit({ repository }),
});
python
import aws_cdk.aws_codecommit as codecommit
repository = codecommit.Repository(self, "MyRepo", repository_name="foo")
codebuild.Project(self, "MyFirstCodeCommitProject",
source=codebuild.Source.code_commit(repository=repository)
)
java
import software.amazon.awscdk.services.codecommit.*;
Repository repository = Repository.Builder.create(this, "MyRepo").repositoryName("foo").build();
Project.Builder.create(this, "MyFirstCodeCommitProject")
.source(Source.codeCommit(CodeCommitSourceProps.builder().repository(repository).build()))
.build();
csharp
using Amazon.CDK.AWS.CodeCommit;
var repository = new Repository(this, "MyRepo", new RepositoryProps { RepositoryName = "foo" });
new Project(this, "MyFirstCodeCommitProject", new ProjectProps {
Source = Source.CodeCommit(new CodeCommitSourceProps { Repository = repository })
});
go
import codecommit "github.com/aws/aws-cdk-go/awscdk"
repository := codecommit.NewRepository(this, jsii.String("MyRepo"), &RepositoryProps{
RepositoryName: jsii.String("foo"),
})
codebuild.NewProject(this, jsii.String("MyFirstCodeCommitProject"), &ProjectProps{
Source: codebuild.Source_CodeCommit(&CodeCommitSourceProps{
Repository: *Repository,
}),
})
S3Source
Create a CodeBuild project with an S3 bucket as the source:
ts
const bucket = new s3.Bucket(this, 'MyBucket');
new codebuild.Project(this, 'MyProject', {
source: codebuild.Source.s3({
bucket: bucket,
path: 'path/to/file.zip',
}),
});
python
bucket = s3.Bucket(self, "MyBucket")
codebuild.Project(self, "MyProject",
source=codebuild.Source.s3(
bucket=bucket,
path="path/to/file.zip"
)
)
java
Bucket bucket = new Bucket(this, "MyBucket");
Project.Builder.create(this, "MyProject")
.source(Source.s3(S3SourceProps.builder()
.bucket(bucket)
.path("path/to/file.zip")
.build()))
.build();
csharp
var bucket = new Bucket(this, "MyBucket");
new Project(this, "MyProject", new ProjectProps {
Source = Source.S3(new S3SourceProps {
Bucket = bucket,
Path = "path/to/file.zip"
})
});
go
bucket := s3.NewBucket(this, jsii.String("MyBucket"))
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Source: codebuild.Source_S3(&S3SourceProps{
Bucket: bucket,
Path: jsii.String("path/to/file.zip"),
}),
})
The CodeBuild role will be granted to read just the given path from the given bucket.
GitHubSource and GitHubEnterpriseSource
These source types can be used to build code from a GitHub repository. Example:
ts
const gitHubSource = codebuild.Source.gitHub({
owner: 'awslabs',
repo: 'aws-cdk', // optional, default: undefined if unspecified will create organization webhook
webhook: true, // optional, default: true if `webhookFilters` were provided, false otherwise
webhookTriggersBatchBuild: true, // optional, default is false
webhookFilters: [
codebuild.FilterGroup
.inEventOf(codebuild.EventAction.PUSH)
.andBranchIs('main')
.andCommitMessageIs('the commit message'),
codebuild.FilterGroup
.inEventOf(codebuild.EventAction.RELEASED)
.andBranchIs('main')
], // optional, by default all pushes and Pull Requests will trigger a build
});
python
git_hub_source = codebuild.Source.git_hub(
owner="awslabs",
repo="aws-cdk", # optional, default: undefined if unspecified will create organization webhook
webhook=True, # optional, default: true if `webhookFilters` were provided, false otherwise
webhook_triggers_batch_build=True, # optional, default is false
webhook_filters=[
codebuild.FilterGroup.in_event_of(codebuild.EventAction.PUSH).and_branch_is("main").and_commit_message_is("the commit message"),
codebuild.FilterGroup.in_event_of(codebuild.EventAction.RELEASED).and_branch_is("main")
]
)
java
ISource gitHubSource = Source.gitHub(GitHubSourceProps.builder()
.owner("awslabs")
.repo("aws-cdk") // optional, default: undefined if unspecified will create organization webhook
.webhook(true) // optional, default: true if `webhookFilters` were provided, false otherwise
.webhookTriggersBatchBuild(true) // optional, default is false
.webhookFilters(List.of(FilterGroup.inEventOf(EventAction.PUSH).andBranchIs("main").andCommitMessageIs("the commit message"), FilterGroup.inEventOf(EventAction.RELEASED).andBranchIs("main")))
.build());
csharp
var gitHubSource = Source.GitHub(new GitHubSourceProps {
Owner = "awslabs",
Repo = "aws-cdk", // optional, default: undefined if unspecified will create organization webhook
Webhook = true, // optional, default: true if `webhookFilters` were provided, false otherwise
WebhookTriggersBatchBuild = true, // optional, default is false
WebhookFilters = new [] { FilterGroup.InEventOf(EventAction.PUSH).AndBranchIs("main").AndCommitMessageIs("the commit message"), FilterGroup.InEventOf(EventAction.RELEASED).AndBranchIs("main") }
});
go
gitHubSource := codebuild.Source_GitHub(&GitHubSourceProps{
Owner: jsii.String("awslabs"),
Repo: jsii.String("aws-cdk"),
// optional, default: undefined if unspecified will create organization webhook
Webhook: jsii.Boolean(true),
// optional, default: true if `webhookFilters` were provided, false otherwise
WebhookTriggersBatchBuild: jsii.Boolean(true),
// optional, default is false
WebhookFilters: []FilterGroup{
codebuild.FilterGroup_InEventOf(codebuild.EventAction_PUSH).AndBranchIs(jsii.String("main")).AndCommitMessageIs(jsii.String("the commit message")),
codebuild.FilterGroup_*InEventOf(codebuild.EventAction_RELEASED).*AndBranchIs(jsii.String("main")),
},
})
The GitHubSource is also able to trigger all repos in GitHub Organizations Example:
ts
const gitHubSource = codebuild.Source.gitHub({
owner: 'aws',
webhookTriggersBatchBuild: true, // optional, default is false
webhookFilters: [
codebuild.FilterGroup
.inEventOf(codebuild.EventAction.WORKFLOW_JOB_QUEUED)
.andRepositoryNameIs("aws-.*")
.andRepositoryNameIsNot("aws-cdk-lib"),
], // optional, by default all pushes and Pull Requests will trigger a build
});
python
git_hub_source = codebuild.Source.git_hub(
owner="aws",
webhook_triggers_batch_build=True, # optional, default is false
webhook_filters=[
codebuild.FilterGroup.in_event_of(codebuild.EventAction.WORKFLOW_JOB_QUEUED).and_repository_name_is("aws-.*").and_repository_name_is_not("aws-cdk-lib")
]
)
java
ISource gitHubSource = Source.gitHub(GitHubSourceProps.builder()
.owner("aws")
.webhookTriggersBatchBuild(true) // optional, default is false
.webhookFilters(List.of(FilterGroup.inEventOf(EventAction.WORKFLOW_JOB_QUEUED).andRepositoryNameIs("aws-.*").andRepositoryNameIsNot("aws-cdk-lib")))
.build());
csharp
var gitHubSource = Source.GitHub(new GitHubSourceProps {
Owner = "aws",
WebhookTriggersBatchBuild = true, // optional, default is false
WebhookFilters = new [] { FilterGroup.InEventOf(EventAction.WORKFLOW_JOB_QUEUED).AndRepositoryNameIs("aws-.*").AndRepositoryNameIsNot("aws-cdk-lib") }
});
go
gitHubSource := codebuild.Source_GitHub(&GitHubSourceProps{
Owner: jsii.String("aws"),
WebhookTriggersBatchBuild: jsii.Boolean(true),
// optional, default is false
WebhookFilters: []FilterGroup{
codebuild.FilterGroup_InEventOf(codebuild.EventAction_WORKFLOW_JOB_QUEUED).AndRepositoryNameIs(jsii.String("aws-.*")).AndRepositoryNameIsNot(jsii.String("aws-cdk-lib")),
},
})
To provide GitHub credentials, please either go to AWS CodeBuild Console to connect or call ImportSourceCredentials to persist your personal access token. Example:
console
aws codebuild import-source-credentials --server-type GITHUB --auth-type PERSONAL_ACCESS_TOKEN --token <token_value>
BitBucketSource
This source type can be used to build code from a BitBucket repository.
ts
const bbSource = codebuild.Source.bitBucket({
owner: 'owner',
repo: 'repo',
});
python
bb_source = codebuild.Source.bit_bucket(
owner="owner",
repo="repo"
)
java
ISource bbSource = Source.bitBucket(BitBucketSourceProps.builder()
.owner("owner")
.repo("repo")
.build());
csharp
var bbSource = Source.BitBucket(new BitBucketSourceProps {
Owner = "owner",
Repo = "repo"
});
go
bbSource := codebuild.Source_BitBucket(&BitBucketSourceProps{
Owner: jsii.String("owner"),
Repo: jsii.String("repo"),
})
For all Git sources
For all Git sources, you can fetch submodules while cloning git repo.
ts
const gitHubSource = codebuild.Source.gitHub({
owner: 'awslabs',
repo: 'aws-cdk',
fetchSubmodules: true,
});
python
git_hub_source = codebuild.Source.git_hub(
owner="awslabs",
repo="aws-cdk",
fetch_submodules=True
)
java
ISource gitHubSource = Source.gitHub(GitHubSourceProps.builder()
.owner("awslabs")
.repo("aws-cdk")
.fetchSubmodules(true)
.build());
csharp
var gitHubSource = Source.GitHub(new GitHubSourceProps {
Owner = "awslabs",
Repo = "aws-cdk",
FetchSubmodules = true
});
go
gitHubSource := codebuild.Source_GitHub(&GitHubSourceProps{
Owner: jsii.String("awslabs"),
Repo: jsii.String("aws-cdk"),
FetchSubmodules: jsii.Boolean(true),
})
BuildSpec
The build spec can be provided from a number of different sources
File path relative to the root of the source
You can specify a specific filename that exists within the project's source artifact to use as the buildspec.
ts
const project = new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromSourceFilename('my-buildspec.yml'),
source: codebuild.Source.gitHub({
owner: 'awslabs',
repo: 'aws-cdk',
})
});
python
project = codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_source_filename("my-buildspec.yml"),
source=codebuild.Source.git_hub(
owner="awslabs",
repo="aws-cdk"
)
)
java
Project project = Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromSourceFilename("my-buildspec.yml"))
.source(Source.gitHub(GitHubSourceProps.builder()
.owner("awslabs")
.repo("aws-cdk")
.build()))
.build();
csharp
var project = new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromSourceFilename("my-buildspec.yml"),
Source = Source.GitHub(new GitHubSourceProps {
Owner = "awslabs",
Repo = "aws-cdk"
})
});
go
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromSourceFilename(jsii.String("my-buildspec.yml")),
Source: codebuild.Source_GitHub(&GitHubSourceProps{
Owner: jsii.String("awslabs"),
Repo: jsii.String("aws-cdk"),
}),
})
This will use my-buildspec.yml file within the awslabs/aws-cdk repository as the build spec.
File within the CDK project codebuild
You can also specify a file within your cdk project directory to use as the buildspec.
ts
const project = new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromAsset('my-buildspec.yml'),
});
python
project = codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_asset("my-buildspec.yml")
)
java
Project project = Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromAsset("my-buildspec.yml"))
.build();
csharp
var project = new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromAsset("my-buildspec.yml")
});
go
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromAsset(jsii.String("my-buildspec.yml")),
})
This file will be uploaded to S3 and referenced from the codebuild project.
Inline object
ts
const project = new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
}),
});
python
project = codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2"
})
)
java
Project project = Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2")))
.build();
csharp
var project = new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" }
})
});
go
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
}),
})
This will result in the buildspec being rendered as JSON within the codebuild project, if you prefer it to be rendered as YAML, use fromObjectToYaml.
ts
const project = new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromObjectToYaml({
version: '0.2',
}),
});
python
project = codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_object_to_yaml({
"version": "0.2"
})
)
java
Project project = Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromObjectToYaml(Map.of(
"version", "0.2")))
.build();
csharp
var project = new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromObjectToYaml(new Dictionary<string, object> {
{ "version", "0.2" }
})
});
go
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObjectToYaml(map[string]interface{}{
"version": jsii.String("0.2"),
}),
})
Artifacts
CodeBuild Projects can produce Artifacts and upload them to S3. For example:
ts
declare const bucket: s3.Bucket;
const project = new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
}),
artifacts: codebuild.Artifacts.s3({
bucket,
includeBuildId: false,
packageZip: true,
path: 'another/path',
identifier: 'AddArtifact1',
}),
});
python
# bucket: s3.Bucket
project = codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2"
}),
artifacts=codebuild.Artifacts.s3(
bucket=bucket,
include_build_id=False,
package_zip=True,
path="another/path",
identifier="AddArtifact1"
)
)
java
Bucket bucket;
Project project = Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2")))
.artifacts(Artifacts.s3(S3ArtifactsProps.builder()
.bucket(bucket)
.includeBuildId(false)
.packageZip(true)
.path("another/path")
.identifier("AddArtifact1")
.build()))
.build();
csharp
Bucket bucket;
var project = new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" }
}),
Artifacts = Artifacts.S3(new S3ArtifactsProps {
Bucket = bucket,
IncludeBuildId = false,
PackageZip = true,
Path = "another/path",
Identifier = "AddArtifact1"
})
});
go
var bucket Bucket
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
}),
Artifacts: codebuild.Artifacts_S3(&S3ArtifactsProps{
Bucket: *Bucket,
IncludeBuildId: jsii.Boolean(false),
PackageZip: jsii.Boolean(true),
Path: jsii.String("another/path"),
Identifier: jsii.String("AddArtifact1"),
}),
})
Because we've not set the name property, this example will set the overrideArtifactName parameter, and produce an artifact named as defined in the Buildspec file, uploaded to an S3 bucket (bucket). The path will be another/path and the artifact will be a zipfile.
CodePipeline
To add a CodeBuild Project as an Action to CodePipeline, use the PipelineProject class instead of Project. It's a simple class that doesn't allow you to specify sources, secondarySources, artifacts or secondaryArtifacts, as these are handled by setting input and output CodePipeline Artifact instances on the Action, instead of setting them on the Project.
ts
const project = new codebuild.PipelineProject(this, 'Project', {
// properties as above...
})
python
project = codebuild.PipelineProject(self, "Project")
java
PipelineProject project = PipelineProject.Builder.create(this, "Project").build();
csharp
var project = new PipelineProject(this, "Project", new PipelineProjectProps { });
go
project := codebuild.NewPipelineProject(this, jsii.String("Project"), &PipelineProjectProps{
})
For more details, see the readme of the @aws-cdk/aws-codepipeline-actions package.
Caching
You can save time when your project builds by using a cache. A cache can store reusable pieces of your build environment and use them across multiple builds. Your build project can use one of two types of caching: Amazon S3 or local. In general, S3 caching is a good option for small and intermediate build artifacts that are more expensive to build than to download. Local caching is a good option for large intermediate build artifacts because the cache is immediately available on the build host.
S3 Caching
With S3 caching, the cache is stored in an S3 bucket which is available regardless from what CodeBuild instance gets selected to run your CodeBuild job on. When using S3 caching, you must also add in a cache section to your buildspec which indicates the files to be cached:
ts
declare const myCachingBucket: s3.Bucket;
new codebuild.Project(this, 'Project', {
source: codebuild.Source.bitBucket({
owner: 'awslabs',
repo: 'aws-cdk',
}),
cache: codebuild.Cache.bucket(myCachingBucket),
// BuildSpec with a 'cache' section necessary for S3 caching. This can
// also come from 'buildspec.yml' in your source.
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: ['...'],
},
},
cache: {
paths: [
// The '**/*' is required to indicate all files in this directory
'/root/cachedir/**/*',
],
},
}),
});
python
# my_caching_bucket: s3.Bucket
codebuild.Project(self, "Project",
source=codebuild.Source.bit_bucket(
owner="awslabs",
repo="aws-cdk"
),
cache=codebuild.Cache.bucket(my_caching_bucket),
# BuildSpec with a 'cache' section necessary for S3 caching. This can
# also come from 'buildspec.yml' in your source.
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["..."]
}
},
"cache": {
"paths": ["/root/cachedir/**/*"
]
}
})
)
java
Bucket myCachingBucket;
Project.Builder.create(this, "Project")
.source(Source.bitBucket(BitBucketSourceProps.builder()
.owner("awslabs")
.repo("aws-cdk")
.build()))
.cache(Cache.bucket(myCachingBucket))
// BuildSpec with a 'cache' section necessary for S3 caching. This can
// also come from 'buildspec.yml' in your source.
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("..."))),
"cache", Map.of(
"paths", List.of("/root/cachedir/**/*")))))
.build();
csharp
Bucket myCachingBucket;
new Project(this, "Project", new ProjectProps {
Source = Source.BitBucket(new BitBucketSourceProps {
Owner = "awslabs",
Repo = "aws-cdk"
}),
Cache = Cache.Bucket(myCachingBucket),
// BuildSpec with a 'cache' section necessary for S3 caching. This can
// also come from 'buildspec.yml' in your source.
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "..." }
} }
} },
{ "cache", new Dictionary<string, string[]> {
{ "paths", new [] { "/root/cachedir/**/*" } }
} }
})
});
go
var myCachingBucket Bucket
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Source: codebuild.Source_BitBucket(&BitBucketSourceProps{
Owner: jsii.String("awslabs"),
Repo: jsii.String("aws-cdk"),
}),
Cache: codebuild.Cache_Bucket(myCachingBucket),
// BuildSpec with a 'cache' section necessary for S3 caching. This can
// also come from 'buildspec.yml' in your source.
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("..."),
},
},
},
"cache": map[string][]*string{
"paths": []*string{
jsii.String("/root/cachedir/**/*"),
},
},
}),
})
If you want to share the same cache between multiple projects, you must must do the following:
- Use the same
cacheNamespace. - Specify the same cache key.
- Define identical cache paths.
- Use the same Amazon S3 buckets and
pathPrefixif set.
ts
declare const sourceBucket: s3.Bucket;
declare const myCachingBucket: s3.Bucket;
new codebuild.Project(this, 'ProjectA', {
source: codebuild.Source.s3({
bucket: sourceBucket,
path: 'path/to/source-a.zip',
}),
// configure the same bucket and path prefix
cache: codebuild.Cache.bucket(myCachingBucket, {
prefix: 'cache',
// use the same cache namespace
cacheNamespace: 'cache-namespace',
}),
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: ['...'],
},
},
// specify the same cache key and paths
cache: {
key: 'unique-key',
paths: [
'/root/cachedir/**/*',
],
},
}),
});
new codebuild.Project(this, 'ProjectB', {
source: codebuild.Source.s3({
bucket: sourceBucket,
path: 'path/to/source-b.zip',
}),
// configure the same bucket and path prefix
cache: codebuild.Cache.bucket(myCachingBucket, {
prefix: 'cache',
// use the same cache namespace
cacheNamespace: 'cache-namespace',
}),
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: ['...'],
},
},
// specify the same cache key and paths
cache: {
key: 'unique-key',
paths: [
'/root/cachedir/**/*',
],
},
}),
});
python
# source_bucket: s3.Bucket
# my_caching_bucket: s3.Bucket
codebuild.Project(self, "ProjectA",
source=codebuild.Source.s3(
bucket=source_bucket,
path="path/to/source-a.zip"
),
# configure the same bucket and path prefix
cache=codebuild.Cache.bucket(my_caching_bucket,
prefix="cache",
# use the same cache namespace
cache_namespace="cache-namespace"
),
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["..."]
}
},
# specify the same cache key and paths
"cache": {
"key": "unique-key",
"paths": ["/root/cachedir/**/*"
]
}
})
)
codebuild.Project(self, "ProjectB",
source=codebuild.Source.s3(
bucket=source_bucket,
path="path/to/source-b.zip"
),
# configure the same bucket and path prefix
cache=codebuild.Cache.bucket(my_caching_bucket,
prefix="cache",
# use the same cache namespace
cache_namespace="cache-namespace"
),
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["..."]
}
},
# specify the same cache key and paths
"cache": {
"key": "unique-key",
"paths": ["/root/cachedir/**/*"
]
}
})
)
java
Bucket sourceBucket;
Bucket myCachingBucket;
Project.Builder.create(this, "ProjectA")
.source(Source.s3(S3SourceProps.builder()
.bucket(sourceBucket)
.path("path/to/source-a.zip")
.build()))
// configure the same bucket and path prefix
.cache(Cache.bucket(myCachingBucket, BucketCacheOptions.builder()
.prefix("cache")
// use the same cache namespace
.cacheNamespace("cache-namespace")
.build()))
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("..."))),
// specify the same cache key and paths
"cache", Map.of(
"key", "unique-key",
"paths", List.of("/root/cachedir/**/*")))))
.build();
Project.Builder.create(this, "ProjectB")
.source(Source.s3(S3SourceProps.builder()
.bucket(sourceBucket)
.path("path/to/source-b.zip")
.build()))
// configure the same bucket and path prefix
.cache(Cache.bucket(myCachingBucket, BucketCacheOptions.builder()
.prefix("cache")
// use the same cache namespace
.cacheNamespace("cache-namespace")
.build()))
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("..."))),
// specify the same cache key and paths
"cache", Map.of(
"key", "unique-key",
"paths", List.of("/root/cachedir/**/*")))))
.build();
csharp
Bucket sourceBucket;
Bucket myCachingBucket;
new Project(this, "ProjectA", new ProjectProps {
Source = Source.S3(new S3SourceProps {
Bucket = sourceBucket,
Path = "path/to/source-a.zip"
}),
// configure the same bucket and path prefix
Cache = Cache.Bucket(myCachingBucket, new BucketCacheOptions {
Prefix = "cache",
// use the same cache namespace
CacheNamespace = "cache-namespace"
}),
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "..." }
} }
} },
// specify the same cache key and paths
{ "cache", new Dictionary<string, object> {
{ "key", "unique-key" },
{ "paths", new [] { "/root/cachedir/**/*" } }
} }
})
});
new Project(this, "ProjectB", new ProjectProps {
Source = Source.S3(new S3SourceProps {
Bucket = sourceBucket,
Path = "path/to/source-b.zip"
}),
// configure the same bucket and path prefix
Cache = Cache.Bucket(myCachingBucket, new BucketCacheOptions {
Prefix = "cache",
// use the same cache namespace
CacheNamespace = "cache-namespace"
}),
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "..." }
} }
} },
// specify the same cache key and paths
{ "cache", new Dictionary<string, object> {
{ "key", "unique-key" },
{ "paths", new [] { "/root/cachedir/**/*" } }
} }
})
});
go
var sourceBucket Bucket
var myCachingBucket Bucket
codebuild.NewProject(this, jsii.String("ProjectA"), &ProjectProps{
Source: codebuild.Source_S3(&S3SourceProps{
Bucket: sourceBucket,
Path: jsii.String("path/to/source-a.zip"),
}),
// configure the same bucket and path prefix
Cache: codebuild.Cache_Bucket(myCachingBucket, &BucketCacheOptions{
Prefix: jsii.String("cache"),
// use the same cache namespace
CacheNamespace: jsii.String("cache-namespace"),
}),
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("..."),
},
},
},
// specify the same cache key and paths
"cache": map[string]interface{}{
"key": jsii.String("unique-key"),
"paths": []*string{
jsii.String("/root/cachedir/**/*"),
},
},
}),
})
codebuild.NewProject(this, jsii.String("ProjectB"), &ProjectProps{
Source: codebuild.Source_*S3(&S3SourceProps{
Bucket: sourceBucket,
Path: jsii.String("path/to/source-b.zip"),
}),
// configure the same bucket and path prefix
Cache: codebuild.Cache_*Bucket(myCachingBucket, &BucketCacheOptions{
Prefix: jsii.String("cache"),
// use the same cache namespace
CacheNamespace: jsii.String("cache-namespace"),
}),
BuildSpec: codebuild.BuildSpec_*FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("..."),
},
},
},
// specify the same cache key and paths
"cache": map[string]interface{}{
"key": jsii.String("unique-key"),
"paths": []*string{
jsii.String("/root/cachedir/**/*"),
},
},
}),
})
Local Caching
With local caching, the cache is stored on the codebuild instance itself. This is simple, cheap and fast, but CodeBuild cannot guarantee a reuse of instance and hence cannot guarantee cache hits. For example, when a build starts and caches files locally, if two subsequent builds start at the same time afterwards only one of those builds would get the cache. Three different cache modes are supported, which can be turned on individually.
LocalCacheMode.SOURCEcaches Git metadata for primary and secondary sources.LocalCacheMode.DOCKER_LAYERcaches existing Docker layers.LocalCacheMode.CUSTOMcaches directories you specify in the buildspec file.
ts
new codebuild.Project(this, 'Project', {
source: codebuild.Source.gitHubEnterprise({
httpsCloneUrl: 'https://my-github-enterprise.com/owner/repo',
}),
// Enable Docker AND custom caching
cache: codebuild.Cache.local(codebuild.LocalCacheMode.DOCKER_LAYER, codebuild.LocalCacheMode.CUSTOM),
// BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
// also come from 'buildspec.yml' in your source.
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: ['...'],
},
},
cache: {
paths: [
// The '**/*' is required to indicate all files in this directory
'/root/cachedir/**/*',
],
},
}),
});
python
codebuild.Project(self, "Project",
source=codebuild.Source.git_hub_enterprise(
https_clone_url="https://my-github-enterprise.com/owner/repo"
),
# Enable Docker AND custom caching
cache=codebuild.Cache.local(codebuild.LocalCacheMode.DOCKER_LAYER, codebuild.LocalCacheMode.CUSTOM),
# BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
# also come from 'buildspec.yml' in your source.
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["..."]
}
},
"cache": {
"paths": ["/root/cachedir/**/*"
]
}
})
)
java
Project.Builder.create(this, "Project")
.source(Source.gitHubEnterprise(GitHubEnterpriseSourceProps.builder()
.httpsCloneUrl("https://my-github-enterprise.com/owner/repo")
.build()))
// Enable Docker AND custom caching
.cache(Cache.local(LocalCacheMode.DOCKER_LAYER, LocalCacheMode.CUSTOM))
// BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
// also come from 'buildspec.yml' in your source.
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("..."))),
"cache", Map.of(
"paths", List.of("/root/cachedir/**/*")))))
.build();
csharp
new Project(this, "Project", new ProjectProps {
Source = Source.GitHubEnterprise(new GitHubEnterpriseSourceProps {
HttpsCloneUrl = "https://my-github-enterprise.com/owner/repo"
}),
// Enable Docker AND custom caching
Cache = Cache.Local(LocalCacheMode.DOCKER_LAYER, LocalCacheMode.CUSTOM),
// BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
// also come from 'buildspec.yml' in your source.
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "..." }
} }
} },
{ "cache", new Dictionary<string, string[]> {
{ "paths", new [] { "/root/cachedir/**/*" } }
} }
})
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Source: codebuild.Source_GitHubEnterprise(&GitHubEnterpriseSourceProps{
HttpsCloneUrl: jsii.String("https://my-github-enterprise.com/owner/repo"),
}),
// Enable Docker AND custom caching
Cache: codebuild.Cache_Local(codebuild.LocalCacheMode_DOCKER_LAYER, codebuild.LocalCacheMode_CUSTOM),
// BuildSpec with a 'cache' section necessary for 'CUSTOM' caching. This can
// also come from 'buildspec.yml' in your source.
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("..."),
},
},
},
"cache": map[string][]*string{
"paths": []*string{
jsii.String("/root/cachedir/**/*"),
},
},
}),
})
Environment
By default, projects use a small instance with an Ubuntu 18.04 image. You can use the environment property to customize the build environment:
buildImagedefines the Docker image used. See Images below for details on how to define build images.certificatedefines the location of a PEM encoded certificate to import.computeTypedefines the instance type used for the build.dockerServerdefines the docker server used for the build.hostKerneldefines the host operating system kernel used for the build. See Host kernel below.privilegedcan be set totrueto allow privileged access.environmentVariablescan be set at this level (and also at the project level).
Finally, you can also set the build environment fleet property to create a reserved capacity project. See Fleet for more information.
Host kernel
CodeBuild runs your build container on a host instance. You can select which host operating system kernel that instance uses with the hostKernel property:
ts
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
hostKernel: codebuild.HostKernel.LINUX_KERNEL_6,
},
});
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.STANDARD_7_0,
host_kernel=codebuild.HostKernel.LINUX_KERNEL_6
)
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(LinuxBuildImage.STANDARD_7_0)
.hostKernel(HostKernel.LINUX_KERNEL_6)
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = LinuxBuildImage.STANDARD_7_0,
HostKernel = HostKernel.LINUX_KERNEL_6
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxBuildImage_STANDARD_7_0(),
HostKernel: codebuild.HostKernel_LINUX_KERNEL_6,
},
})
The host kernel does not affect the build environment operating system, which is determined by the buildImage. Use HostKernel.LINUX_KERNEL_LATEST to always run on the latest supported host kernel.
This setting only applies to the LINUX_CONTAINER, ARM_CONTAINER, LINUX_EC2 and ARM_EC2 environment types. Specifying it with a Windows, Lambda or Mac build image results in a validation error at synthesis time.
Images
The CodeBuild library supports Linux, Windows, and Mac images via the LinuxBuildImage (or LinuxArmBuildImage), WindowsBuildImage, and MacBuildImage classes, respectively. With the introduction of Lambda compute support, the LinuxLambdaBuildImage (or LinuxArmLambdaBuildImage) class is available for specifying Lambda-compatible images.
You can specify one of the predefined Windows/Linux images by using one of the constants such as WindowsBuildImage.WIN_SERVER_CORE_2019_BASE, WindowsBuildImage.WINDOWS_BASE_2_0, LinuxBuildImage.STANDARD_2_0, LinuxBuildImage.AMAZON_LINUX_2_5, MacBuildImage.BASE_14, MacBuildImage.BASE_15, MacBuildImage.BASE_26, LinuxArmBuildImage.AMAZON_LINUX_2_ARM, LinuxLambdaBuildImage.AMAZON_LINUX_2_NODE_18, LinuxLambdaBuildImage.AMAZON_LINUX_2023_NODE_24, LinuxArmLambdaBuildImage.AMAZON_LINUX_2_NODE_18 or LinuxArmLambdaBuildImage.AMAZON_LINUX_2023_NODE_24.
Alternatively, you can specify a custom image using one of the static methods on LinuxBuildImage:
LinuxBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }])to reference an image in any public or private Docker registry.LinuxBuildImage.fromEcrRepository(repo[, tag])to reference an image available in an ECR repository.LinuxBuildImage.fromAsset(parent, id, props)to use an image created from a local asset.LinuxBuildImage.fromCodeBuildImageId(id)to reference a pre-defined, CodeBuild-provided Docker image.
or one of the corresponding methods on WindowsBuildImage:
WindowsBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }, imageType])WindowsBuildImage.fromEcrRepository(repo[, tag, imageType])WindowsBuildImage.fromAsset(parent, id, props, [, imageType])
or one of the corresponding methods on MacBuildImage:
MacBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }, imageType])MacBuildImage.fromEcrRepository(repo[, tag, imageType])MacBuildImage.fromAsset(parent, id, props, [, imageType])
or one of the corresponding methods on LinuxArmBuildImage:
LinuxArmBuildImage.fromDockerRegistry(image[, { secretsManagerCredentials }])LinuxArmBuildImage.fromEcrRepository(repo[, tag])
Note: You cannot specify custom images on LinuxLambdaBuildImage or LinuxArmLambdaBuildImage images.
Note that the WindowsBuildImage version of the static methods accepts an optional parameter of type WindowsImageType, which can be either WindowsImageType.STANDARD, the default, or WindowsImageType.SERVER_2019:
ts
declare const ecrRepository: ecr.Repository;
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.WindowsBuildImage.fromEcrRepository(ecrRepository, 'v1.0', codebuild.WindowsImageType.SERVER_2019),
// optional certificate to include in the build image
certificate: {
bucket: s3.Bucket.fromBucketName(this, 'Bucket', 'amzn-s3-demo-bucket'),
objectKey: 'path/to/cert.pem',
},
},
// ...
})
python
# ecr_repository: ecr.Repository
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.WindowsBuildImage.from_ecr_repository(ecr_repository, "v1.0", codebuild.WindowsImageType.SERVER_2019),
# optional certificate to include in the build image
certificate=codebuild.BuildEnvironmentCertificate(
bucket=s3.Bucket.from_bucket_name(self, "Bucket", "amzn-s3-demo-bucket"),
object_key="path/to/cert.pem"
)
)
)
java
Repository ecrRepository;
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(WindowsBuildImage.fromEcrRepository(ecrRepository, "v1.0", WindowsImageType.SERVER_2019))
// optional certificate to include in the build image
.certificate(BuildEnvironmentCertificate.builder()
.bucket(Bucket.fromBucketName(this, "Bucket", "amzn-s3-demo-bucket"))
.objectKey("path/to/cert.pem")
.build())
.build())
.build();
csharp
Repository ecrRepository;
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = WindowsBuildImage.FromEcrRepository(ecrRepository, "v1.0", WindowsImageType.SERVER_2019),
// optional certificate to include in the build image
Certificate = new BuildEnvironmentCertificate {
Bucket = Bucket.FromBucketName(this, "Bucket", "amzn-s3-demo-bucket"),
ObjectKey = "path/to/cert.pem"
}
}
});
go
var ecrRepository Repository
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.WindowsBuildImage_FromEcrRepository(ecrRepository, jsii.String("v1.0"), codebuild.WindowsImageType_SERVER_2019),
// optional certificate to include in the build image
Certificate: &BuildEnvironmentCertificate{
Bucket: s3.Bucket_FromBucketName(this, jsii.String("Bucket"), jsii.String("amzn-s3-demo-bucket")),
ObjectKey: jsii.String("path/to/cert.pem"),
},
},
})
The following example shows how to define an image from a Docker asset:
ts
environment: {
buildImage: codebuild.LinuxBuildImage.fromAsset(this, 'MyImage', {
directory: path.join(__dirname, 'demo-image'),
}),
},
python
environment=cdk.aws_codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.from_asset(self, "MyImage",
directory=path.join(__dirname, "demo-image")
)
)
java
.environment(BuildEnvironment.builder()
.buildImage(LinuxBuildImage.fromAsset(this, "MyImage", DockerImageAssetProps.builder()
.directory(join(__dirname, "demo-image"))
.build()))
.build())
.build();
csharp
Environment = new BuildEnvironment {
BuildImage = LinuxBuildImage.FromAsset(this, "MyImage", new DockerImageAssetProps {
Directory = Join(__dirname, "demo-image")
})
}
go
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxBuildImage_FromAsset(this, jsii.String("MyImage"), &DockerImageAssetProps{
Directory: path.join(__dirname, jsii.String("demo-image")),
}),
},
The following example shows how to define an image from an ECR repository:
ts
environment: {
buildImage: codebuild.LinuxBuildImage.fromEcrRepository(ecrRepository, 'v1.0'),
},
python
environment=cdk.aws_codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.from_ecr_repository(ecr_repository, "v1.0")
)
java
.environment(BuildEnvironment.builder()
.buildImage(LinuxBuildImage.fromEcrRepository(ecrRepository, "v1.0"))
.build())
.build();
csharp
Environment = new BuildEnvironment {
BuildImage = LinuxBuildImage.FromEcrRepository(ecrRepository, "v1.0")
}
go
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxBuildImage_FromEcrRepository(ecrRepository, jsii.String("v1.0")),
},
The following example shows how to define an image from a private docker registry:
ts
environment: {
buildImage: codebuild.LinuxBuildImage.fromDockerRegistry('my-registry/my-repo', {
secretsManagerCredentials: secrets,
}),
},
python
environment=cdk.aws_codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.from_docker_registry("my-registry/my-repo",
secrets_manager_credentials=secrets
)
)
java
.environment(BuildEnvironment.builder()
.buildImage(LinuxBuildImage.fromDockerRegistry("my-registry/my-repo", DockerImageOptions.builder()
.secretsManagerCredentials(secrets)
.build()))
.build())
.build();
csharp
Environment = new BuildEnvironment {
BuildImage = LinuxBuildImage.FromDockerRegistry("my-registry/my-repo", new DockerImageOptions {
SecretsManagerCredentials = secrets
})
}
go
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxBuildImage_FromDockerRegistry(jsii.String("my-registry/my-repo"), &DockerImageOptions{
SecretsManagerCredentials: secrets,
}),
},
GPU images
The class LinuxGpuBuildImage contains constants for working with AWS Deep Learning Container images:
ts
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.LinuxGpuBuildImage.DLC_TENSORFLOW_2_1_0_INFERENCE,
},
// ...
})
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxGpuBuildImage.DLC_TENSORFLOW_2_1_0_INFERENCE
)
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(LinuxGpuBuildImage.DLC_TENSORFLOW_2_1_0_INFERENCE)
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = LinuxGpuBuildImage.DLC_TENSORFLOW_2_1_0_INFERENCE
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxGpuBuildImage_DLC_TENSORFLOW_2_1_0_INFERENCE(),
},
})
One complication is that the repositories for the DLC images are in different accounts in different AWS regions. In most cases, the CDK will handle providing the correct account for you; in rare cases (for example, deploying to new regions) where our information might be out of date, you can always specify the account (along with the repository name and tag) explicitly using the awsDeepLearningContainersImage method:
ts
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.LinuxGpuBuildImage.awsDeepLearningContainersImage(
'tensorflow-inference', '2.1.0-gpu-py36-cu101-ubuntu18.04', '123456789012'),
},
// ...
})
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxGpuBuildImage.aws_deep_learning_containers_image("tensorflow-inference", "2.1.0-gpu-py36-cu101-ubuntu18.04", "123456789012")
)
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(LinuxGpuBuildImage.awsDeepLearningContainersImage("tensorflow-inference", "2.1.0-gpu-py36-cu101-ubuntu18.04", "123456789012"))
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = LinuxGpuBuildImage.AwsDeepLearningContainersImage("tensorflow-inference", "2.1.0-gpu-py36-cu101-ubuntu18.04", "123456789012")
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxGpuBuildImage_AwsDeepLearningContainersImage(jsii.String("tensorflow-inference"), jsii.String("2.1.0-gpu-py36-cu101-ubuntu18.04"), jsii.String("123456789012")),
},
})
Alternatively, you can reference an image available in an ECR repository using the LinuxGpuBuildImage.fromEcrRepository(repo[, tag]) method.
Lambda images
The LinuxLambdaBuildImage (or LinuxArmLambdaBuildImage) class contains constants for working with Lambda compute:
ts
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.LinuxLambdaBuildImage.AMAZON_LINUX_2_NODE_18,
},
// ...
})
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxLambdaBuildImage.AMAZON_LINUX_2_NODE_18
)
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(LinuxLambdaBuildImage.AMAZON_LINUX_2_NODE_18)
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = LinuxLambdaBuildImage.AMAZON_LINUX_2_NODE_18
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxLambdaBuildImage_AMAZON_LINUX_2_NODE_18(),
},
})
Visit AWS Lambda compute in AWS CodeBuild for more details.
Fleet
By default, a CodeBuild project will request on-demand compute resources to process your build requests. While being able to scale and handle high load, on-demand resources can also be slow to provision.
Reserved capacity fleets are an alternative to on-demand. Dedicated instances, maintained by CodeBuild, will be ready to fulfill your build requests immediately. Skipping the provisioning step in your project will reduce your build time, at the cost of paying for these reserved instances, even when idling, until they are released.
For more information, see Working with reserved capacity in AWS CodeBuild in the CodeBuild documentation.
ts
const fleet = new codebuild.Fleet(this, 'Fleet', {
computeType: codebuild.FleetComputeType.MEDIUM,
environmentType: codebuild.EnvironmentType.LINUX_CONTAINER,
baseCapacity: 1,
});
new codebuild.Project(this, 'Project', {
environment: {
fleet,
buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
},
// ...
})
python
fleet = codebuild.Fleet(self, "Fleet",
compute_type=codebuild.FleetComputeType.MEDIUM,
environment_type=codebuild.EnvironmentType.LINUX_CONTAINER,
base_capacity=1
)
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
fleet=fleet,
build_image=codebuild.LinuxBuildImage.STANDARD_7_0
)
)
java
Fleet fleet = Fleet.Builder.create(this, "Fleet")
.computeType(FleetComputeType.MEDIUM)
.environmentType(EnvironmentType.LINUX_CONTAINER)
.baseCapacity(1)
.build();
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.fleet(fleet)
.buildImage(LinuxBuildImage.STANDARD_7_0)
.build())
.build();
csharp
var fleet = new Fleet(this, "Fleet", new FleetProps {
ComputeType = FleetComputeType.MEDIUM,
EnvironmentType = EnvironmentType.LINUX_CONTAINER,
BaseCapacity = 1
});
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
Fleet = fleet,
BuildImage = LinuxBuildImage.STANDARD_7_0
}
});
go
fleet := codebuild.NewFleet(this, jsii.String("Fleet"), &FleetProps{
ComputeType: codebuild.FleetComputeType_MEDIUM,
EnvironmentType: codebuild.EnvironmentType_LINUX_CONTAINER,
BaseCapacity: jsii.Number(1),
})
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
Fleet: *Fleet,
BuildImage: codebuild.LinuxBuildImage_STANDARD_7_0(),
},
})
You can also import an existing fleet to share its resources among several projects across multiple stacks:
ts
new codebuild.Project(this, 'Project', {
environment: {
fleet: codebuild.Fleet.fromFleetArn(
this, 'SharedFleet',
'arn:aws:codebuild:us-east-1:123456789012:fleet/MyFleet:ed0d0823-e38a-4c10-90a1-1bf25f50fa76',
),
buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
},
// ...
})
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
fleet=codebuild.Fleet.from_fleet_arn(self, "SharedFleet", "arn:aws:codebuild:us-east-1:123456789012:fleet/MyFleet:ed0d0823-e38a-4c10-90a1-1bf25f50fa76"),
build_image=codebuild.LinuxBuildImage.STANDARD_7_0
)
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.fleet(Fleet.fromFleetArn(this, "SharedFleet", "arn:aws:codebuild:us-east-1:123456789012:fleet/MyFleet:ed0d0823-e38a-4c10-90a1-1bf25f50fa76"))
.buildImage(LinuxBuildImage.STANDARD_7_0)
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
Fleet = Fleet.FromFleetArn(this, "SharedFleet", "arn:aws:codebuild:us-east-1:123456789012:fleet/MyFleet:ed0d0823-e38a-4c10-90a1-1bf25f50fa76"),
BuildImage = LinuxBuildImage.STANDARD_7_0
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
Fleet: codebuild.Fleet_FromFleetArn(this, jsii.String("SharedFleet"), jsii.String("arn:aws:codebuild:us-east-1:123456789012:fleet/MyFleet:ed0d0823-e38a-4c10-90a1-1bf25f50fa76")),
BuildImage: codebuild.LinuxBuildImage_STANDARD_7_0(),
},
})
Attribute-based compute
You can use attribute-based compute for your fleet by setting the computeType to ATTRIBUTE_BASED. This allows you to specify the attributes in computeConfiguration such as vCPUs, memory, disk space, and the machineType. After specifying some or all of the available attributes, CodeBuild will select the cheapest compute type from available instance types as that at least matches all given criteria.
ts
import { Size } from 'aws-cdk-lib';
const fleet = new codebuild.Fleet(this, 'MyFleet', {
baseCapacity: 1,
computeType: codebuild.FleetComputeType.ATTRIBUTE_BASED,
environmentType: codebuild.EnvironmentType.LINUX_CONTAINER,
computeConfiguration: {
vCpu: 2,
memory: Size.gibibytes(4),
disk: Size.gibibytes(10),
machineType: codebuild.MachineType.GENERAL,
},
});
python
from aws_cdk import Size
fleet = codebuild.Fleet(self, "MyFleet",
base_capacity=1,
compute_type=codebuild.FleetComputeType.ATTRIBUTE_BASED,
environment_type=codebuild.EnvironmentType.LINUX_CONTAINER,
compute_configuration=codebuild.ComputeConfiguration(
v_cpu=2,
memory=Size.gibibytes(4),
disk=Size.gibibytes(10),
machine_type=codebuild.MachineType.GENERAL
)
)
java
import software.amazon.awscdk.Size;
Fleet fleet = Fleet.Builder.create(this, "MyFleet")
.baseCapacity(1)
.computeType(FleetComputeType.ATTRIBUTE_BASED)
.environmentType(EnvironmentType.LINUX_CONTAINER)
.computeConfiguration(ComputeConfiguration.builder()
.vCpu(2)
.memory(Size.gibibytes(4))
.disk(Size.gibibytes(10))
.machineType(MachineType.GENERAL)
.build())
.build();
csharp
using Amazon.CDK;
var fleet = new Fleet(this, "MyFleet", new FleetProps {
BaseCapacity = 1,
ComputeType = FleetComputeType.ATTRIBUTE_BASED,
EnvironmentType = EnvironmentType.LINUX_CONTAINER,
ComputeConfiguration = new ComputeConfiguration {
VCpu = 2,
Memory = Size.Gibibytes(4),
Disk = Size.Gibibytes(10),
MachineType = MachineType.GENERAL
}
});
go
import "github.com/aws/aws-cdk-go/awscdk"
fleet := codebuild.NewFleet(this, jsii.String("MyFleet"), &FleetProps{
BaseCapacity: jsii.Number(1),
ComputeType: codebuild.FleetComputeType_ATTRIBUTE_BASED,
EnvironmentType: codebuild.EnvironmentType_LINUX_CONTAINER,
ComputeConfiguration: &ComputeConfiguration{
VCpu: jsii.Number(2),
Memory: awscdk.Size_Gibibytes(jsii.Number(4)),
Disk: awscdk.Size_*Gibibytes(jsii.Number(10)),
MachineType: codebuild.MachineType_GENERAL,
},
})
Custom instance types
You can use specific EC2 instance types for your fleet by setting the computeType to CUSTOM_INSTANCE_TYPE. This allows you to specify the instanceType in computeConfiguration. Only certain EC2 instance types are supported; see the linked documentation for details.
ts
import { Size } from 'aws-cdk-lib';
const fleet = new codebuild.Fleet(this, 'MyFleet', {
baseCapacity: 1,
computeType: codebuild.FleetComputeType.CUSTOM_INSTANCE_TYPE,
environmentType: codebuild.EnvironmentType.LINUX_CONTAINER,
computeConfiguration: {
instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MEDIUM),
// By default, 64 GiB of disk space is included. Any value optionally
// specified here is _incremental_ on top of the included disk space.
disk: Size.gibibytes(10),
},
});
python
from aws_cdk import Size
fleet = codebuild.Fleet(self, "MyFleet",
base_capacity=1,
compute_type=codebuild.FleetComputeType.CUSTOM_INSTANCE_TYPE,
environment_type=codebuild.EnvironmentType.LINUX_CONTAINER,
compute_configuration=codebuild.ComputeConfiguration(
instance_type=ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MEDIUM),
# By default, 64 GiB of disk space is included. Any value optionally
# specified here is _incremental_ on top of the included disk space.
disk=Size.gibibytes(10)
)
)
java
import software.amazon.awscdk.Size;
Fleet fleet = Fleet.Builder.create(this, "MyFleet")
.baseCapacity(1)
.computeType(FleetComputeType.CUSTOM_INSTANCE_TYPE)
.environmentType(EnvironmentType.LINUX_CONTAINER)
.computeConfiguration(ComputeConfiguration.builder()
.instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MEDIUM))
// By default, 64 GiB of disk space is included. Any value optionally
// specified here is _incremental_ on top of the included disk space.
.disk(Size.gibibytes(10))
.build())
.build();
csharp
using Amazon.CDK;
var fleet = new Fleet(this, "MyFleet", new FleetProps {
BaseCapacity = 1,
ComputeType = FleetComputeType.CUSTOM_INSTANCE_TYPE,
EnvironmentType = EnvironmentType.LINUX_CONTAINER,
ComputeConfiguration = new ComputeConfiguration {
InstanceType = InstanceType.Of(InstanceClass.T3, InstanceSize.MEDIUM),
// By default, 64 GiB of disk space is included. Any value optionally
// specified here is _incremental_ on top of the included disk space.
Disk = Size.Gibibytes(10)
}
});
go
import "github.com/aws/aws-cdk-go/awscdk"
fleet := codebuild.NewFleet(this, jsii.String("MyFleet"), &FleetProps{
BaseCapacity: jsii.Number(1),
ComputeType: codebuild.FleetComputeType_CUSTOM_INSTANCE_TYPE,
EnvironmentType: codebuild.EnvironmentType_LINUX_CONTAINER,
ComputeConfiguration: &ComputeConfiguration{
InstanceType: ec2.InstanceType_Of(ec2.InstanceClass_T3, ec2.InstanceSize_MEDIUM),
// By default, 64 GiB of disk space is included. Any value optionally
// specified here is _incremental_ on top of the included disk space.
Disk: awscdk.Size_Gibibytes(jsii.Number(10)),
},
})
Fleet overflow behavior
When your builds exceed the capacity of your fleet, you can specify how CodeBuild should handle the overflow builds by setting the overflowBehavior property:
ts
const fleet = new codebuild.Fleet(this, 'Fleet', {
computeType: codebuild.FleetComputeType.MEDIUM,
environmentType: codebuild.EnvironmentType.LINUX_CONTAINER,
baseCapacity: 1,
overflowBehavior: codebuild.FleetOverflowBehavior.ON_DEMAND,
});
python
fleet = codebuild.Fleet(self, "Fleet",
compute_type=codebuild.FleetComputeType.MEDIUM,
environment_type=codebuild.EnvironmentType.LINUX_CONTAINER,
base_capacity=1,
overflow_behavior=codebuild.FleetOverflowBehavior.ON_DEMAND
)
java
Fleet fleet = Fleet.Builder.create(this, "Fleet")
.computeType(FleetComputeType.MEDIUM)
.environmentType(EnvironmentType.LINUX_CONTAINER)
.baseCapacity(1)
.overflowBehavior(FleetOverflowBehavior.ON_DEMAND)
.build();
csharp
var fleet = new Fleet(this, "Fleet", new FleetProps {
ComputeType = FleetComputeType.MEDIUM,
EnvironmentType = EnvironmentType.LINUX_CONTAINER,
BaseCapacity = 1,
OverflowBehavior = FleetOverflowBehavior.ON_DEMAND
});
go
fleet := codebuild.NewFleet(this, jsii.String("Fleet"), &FleetProps{
ComputeType: codebuild.FleetComputeType_MEDIUM,
EnvironmentType: codebuild.EnvironmentType_LINUX_CONTAINER,
BaseCapacity: jsii.Number(1),
OverflowBehavior: codebuild.FleetOverflowBehavior_ON_DEMAND,
})
The available overflow behaviors are:
QUEUE(default): Overflow builds wait for existing fleet instances to become availableON_DEMAND: Overflow builds run on CodeBuild on-demand instances
Note: If you set overflow behavior to ON_DEMAND for a VPC-connected fleet, ensure your VPC settings allow access to public AWS services.
VPCs
The same considerations that apply to Project VPCs also apply to Fleet VPCs. When using a Fleet in a CodeBuild Project, it is an error to configure a VPC on the Project. Configure a VPC on the fleet instead.
ts
declare const loadBalancer: elbv2.ApplicationLoadBalancer;
const vpc = new ec2.Vpc(this, 'MyVPC');
const fleet = new codebuild.Fleet(this, 'MyProject', {
computeType: codebuild.FleetComputeType.MEDIUM,
environmentType: codebuild.EnvironmentType.LINUX_CONTAINER,
baseCapacity: 1,
vpc,
});
fleet.connections.allowTo(loadBalancer, ec2.Port.tcp(443));
const project = new codebuild.Project(this, 'MyProject', {
environment: {
fleet,
},
buildSpec: codebuild.BuildSpec.fromObject({
// ...
}),
// Trying to configure a project-level VPC is an error, because this project
// runs on the Fleet created above.
// vpc,
});
python
# load_balancer: elbv2.ApplicationLoadBalancer
vpc = ec2.Vpc(self, "MyVPC")
fleet = codebuild.Fleet(self, "MyProject",
compute_type=codebuild.FleetComputeType.MEDIUM,
environment_type=codebuild.EnvironmentType.LINUX_CONTAINER,
base_capacity=1,
vpc=vpc
)
fleet.connections.allow_to(load_balancer, ec2.Port.tcp(443))
project = codebuild.Project(self, "MyProject",
environment=codebuild.BuildEnvironment(
fleet=fleet
),
build_spec=codebuild.BuildSpec.from_object({})
)
java
ApplicationLoadBalancer loadBalancer;
Vpc vpc = new Vpc(this, "MyVPC");
Fleet fleet = Fleet.Builder.create(this, "MyProject")
.computeType(FleetComputeType.MEDIUM)
.environmentType(EnvironmentType.LINUX_CONTAINER)
.baseCapacity(1)
.vpc(vpc)
.build();
fleet.connections.allowTo(loadBalancer, Port.tcp(443));
Project project = Project.Builder.create(this, "MyProject")
.environment(BuildEnvironment.builder()
.fleet(fleet)
.build())
.buildSpec(BuildSpec.fromObject(Map.of()))
.build();
csharp
ApplicationLoadBalancer loadBalancer;
var vpc = new Vpc(this, "MyVPC");
var fleet = new Fleet(this, "MyProject", new FleetProps {
ComputeType = FleetComputeType.MEDIUM,
EnvironmentType = EnvironmentType.LINUX_CONTAINER,
BaseCapacity = 1,
Vpc = vpc
});
fleet.Connections.AllowTo(loadBalancer, Port.Tcp(443));
var project = new Project(this, "MyProject", new ProjectProps {
Environment = new BuildEnvironment {
Fleet = fleet
},
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> { })
});
go
var loadBalancer ApplicationLoadBalancer
vpc := ec2.NewVpc(this, jsii.String("MyVPC"))
fleet := codebuild.NewFleet(this, jsii.String("MyProject"), &FleetProps{
ComputeType: codebuild.FleetComputeType_MEDIUM,
EnvironmentType: codebuild.EnvironmentType_LINUX_CONTAINER,
BaseCapacity: jsii.Number(1),
Vpc: Vpc,
})
fleet.connections.AllowTo(loadBalancer, ec2.Port_Tcp(jsii.Number(443)))
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Environment: &BuildEnvironment{
Fleet: *Fleet,
},
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
}),
})
Logs
CodeBuild lets you specify an S3 Bucket, CloudWatch Log Group or both to receive logs from your projects.
By default, logs will go to cloudwatch.
CloudWatch Logs Example
ts
new codebuild.Project(this, 'Project', {
logging: {
cloudWatch: {
logGroup: new logs.LogGroup(this, `MyLogGroup`),
}
},
})
python
codebuild.Project(self, "Project",
logging=codebuild.LoggingOptions(
cloud_watch=codebuild.CloudWatchLoggingOptions(
log_group=logs.LogGroup(self, "MyLogGroup")
)
)
)
java
Project.Builder.create(this, "Project")
.logging(LoggingOptions.builder()
.cloudWatch(CloudWatchLoggingOptions.builder()
.logGroup(new LogGroup(this, "MyLogGroup"))
.build())
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Logging = new LoggingOptions {
CloudWatch = new CloudWatchLoggingOptions {
LogGroup = new LogGroup(this, "MyLogGroup")
}
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Logging: &LoggingOptions{
CloudWatch: &CloudWatchLoggingOptions{
LogGroup: logs.NewLogGroup(this, jsii.String("MyLogGroup")),
},
},
})
S3 Logs Example
ts
new codebuild.Project(this, 'Project', {
logging: {
s3: {
bucket: new s3.Bucket(this, `LogBucket`)
}
},
})
python
codebuild.Project(self, "Project",
logging=codebuild.LoggingOptions(
s3=codebuild.S3LoggingOptions(
bucket=s3.Bucket(self, "LogBucket")
)
)
)
java
Project.Builder.create(this, "Project")
.logging(LoggingOptions.builder()
.s3(S3LoggingOptions.builder()
.bucket(new Bucket(this, "LogBucket"))
.build())
.build())
.build();
csharp
new Project(this, "Project", new ProjectProps {
Logging = new LoggingOptions {
S3 = new S3LoggingOptions {
Bucket = new Bucket(this, "LogBucket")
}
}
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Logging: &LoggingOptions{
S3: &S3LoggingOptions{
Bucket: s3.NewBucket(this, jsii.String("LogBucket")),
},
},
})
Debugging builds interactively using SSM Session Manager
Integration with SSM Session Manager makes it possible to add breakpoints to your build commands, pause the build there and log into the container to interactively debug the environment.
To do so, you need to:
- Create the build with
ssmSessionPermissions: true. - Use a build image with SSM agent installed and configured (default CodeBuild images come with the image preinstalled).
- Start the build with debugSessionEnabled set to true.
If these conditions are met, execution of the command codebuild-breakpoint will suspend your build and allow you to attach a Session Manager session from the CodeBuild console.
For more information, see View a running build in Session Manager in the CodeBuild documentation.
Example:
ts
new codebuild.Project(this, 'Project', {
environment: {
buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
},
ssmSessionPermissions: true,
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: [
// Pause the build container if possible
'codebuild-breakpoint',
// Regular build in a script in the repository
'./my-build.sh',
],
},
},
}),
})
python
codebuild.Project(self, "Project",
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.STANDARD_7_0
),
ssm_session_permissions=True,
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["codebuild-breakpoint", "./my-build.sh"
]
}
}
})
)
java
Project.Builder.create(this, "Project")
.environment(BuildEnvironment.builder()
.buildImage(LinuxBuildImage.STANDARD_7_0)
.build())
.ssmSessionPermissions(true)
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("codebuild-breakpoint", "./my-build.sh"))))))
.build();
csharp
new Project(this, "Project", new ProjectProps {
Environment = new BuildEnvironment {
BuildImage = LinuxBuildImage.STANDARD_7_0
},
SsmSessionPermissions = true,
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "codebuild-breakpoint", "./my-build.sh" }
} }
} }
})
});
go
codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Environment: &BuildEnvironment{
BuildImage: codebuild.LinuxBuildImage_STANDARD_7_0(),
},
SsmSessionPermissions: jsii.Boolean(true),
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("codebuild-breakpoint"),
jsii.String("./my-build.sh"),
},
},
},
}),
})
Credentials
CodeBuild allows you to store credentials used when communicating with various sources, like GitHub:
ts
new codebuild.GitHubSourceCredentials(this, 'CodeBuildGitHubCreds', {
accessToken: SecretValue.secretsManager('my-token'),
});
// GitHub Enterprise is almost the same,
// except the class is called GitHubEnterpriseSourceCredentials
python
codebuild.GitHubSourceCredentials(self, "CodeBuildGitHubCreds",
access_token=SecretValue.secrets_manager("my-token")
)
java
GitHubSourceCredentials.Builder.create(this, "CodeBuildGitHubCreds")
.accessToken(SecretValue.secretsManager("my-token"))
.build();
csharp
new GitHubSourceCredentials(this, "CodeBuildGitHubCreds", new GitHubSourceCredentialsProps {
AccessToken = SecretValue.SecretsManager("my-token")
});
go
codebuild.NewGitHubSourceCredentials(this, jsii.String("CodeBuildGitHubCreds"), &GitHubSourceCredentialsProps{
AccessToken: awscdk.SecretValue_SecretsManager(jsii.String("my-token")),
})
and BitBucket:
ts
new codebuild.BitBucketSourceCredentials(this, 'CodeBuildBitBucketCreds', {
username: SecretValue.secretsManager('my-bitbucket-creds', { jsonField: 'username' }),
password: SecretValue.secretsManager('my-bitbucket-creds', { jsonField: 'password' }),
});
python
codebuild.BitBucketSourceCredentials(self, "CodeBuildBitBucketCreds",
username=SecretValue.secrets_manager("my-bitbucket-creds", json_field="username"),
password=SecretValue.secrets_manager("my-bitbucket-creds", json_field="password")
)
java
BitBucketSourceCredentials.Builder.create(this, "CodeBuildBitBucketCreds")
.username(SecretValue.secretsManager("my-bitbucket-creds", SecretsManagerSecretOptions.builder().jsonField("username").build()))
.password(SecretValue.secretsManager("my-bitbucket-creds", SecretsManagerSecretOptions.builder().jsonField("password").build()))
.build();
csharp
new BitBucketSourceCredentials(this, "CodeBuildBitBucketCreds", new BitBucketSourceCredentialsProps {
Username = SecretValue.SecretsManager("my-bitbucket-creds", new SecretsManagerSecretOptions { JsonField = "username" }),
Password = SecretValue.SecretsManager("my-bitbucket-creds", new SecretsManagerSecretOptions { JsonField = "password" })
});
go
codebuild.NewBitBucketSourceCredentials(this, jsii.String("CodeBuildBitBucketCreds"), &BitBucketSourceCredentialsProps{
Username: awscdk.SecretValue_SecretsManager(jsii.String("my-bitbucket-creds"), &SecretsManagerSecretOptions{
JsonField: jsii.String("username"),
}),
Password: awscdk.SecretValue_*SecretsManager(jsii.String("my-bitbucket-creds"), &SecretsManagerSecretOptions{
JsonField: jsii.String("password"),
}),
})
Note: the credentials are global to a given account in a given region - they are not defined per CodeBuild project. CodeBuild only allows storing a single credential of a given type (GitHub, GitHub Enterprise or BitBucket) in a given account in a given region - any attempt to save more than one will result in an error. You can use the list-source-credentials AWS CLI operation to inspect what credentials are stored in your account.
Test reports
You can specify a test report in your buildspec:
ts
const project = new codebuild.Project(this, 'Project', {
buildSpec: codebuild.BuildSpec.fromObject({
// ...
reports: {
myReport: {
files: '**/*',
'base-directory': 'build/test-results',
},
},
}),
});
python
project = codebuild.Project(self, "Project",
build_spec=codebuild.BuildSpec.from_object({
# ...
"reports": {
"my_report": {
"files": "**/*",
"base-directory": "build/test-results"
}
}
})
)
java
Project project = Project.Builder.create(this, "Project")
.buildSpec(BuildSpec.fromObject(Map.of(
// ...
"reports", Map.of(
"myReport", Map.of(
"files", "**/*",
"base-directory", "build/test-results")))))
.build();
csharp
var project = new Project(this, "Project", new ProjectProps {
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
// ...
{ "reports", new Dictionary<string, IDictionary<string, string>> {
{ "myReport", new Struct {
Files = "**/*",
Base-directory = "build/test-results"
} }
} }
})
});
go
project := codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
// ...
"reports": map[string]map[string]*string{
"myReport": map[string]*string{
"files": jsii.String("**/*"),
"base-directory": jsii.String("build/test-results"),
},
},
}),
})
This will create a new test report group, with the name <ProjectName>-myReport.
The project's role in the CDK will always be granted permissions to create and use report groups with names starting with the project's name; if you'd rather not have those permissions added, you can opt out of it when creating the project:
ts
declare const source: codebuild.Source;
const project = new codebuild.Project(this, 'Project', {
source,
grantReportGroupPermissions: false,
});
python
# source: codebuild.Source
project = codebuild.Project(self, "Project",
source=source,
grant_report_group_permissions=False
)
java
Source source;
Project project = Project.Builder.create(this, "Project")
.source(source)
.grantReportGroupPermissions(false)
.build();
csharp
Source source;
var project = new Project(this, "Project", new ProjectProps {
Source = source,
GrantReportGroupPermissions = false
});
go
var source Source
project := codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Source: Source,
GrantReportGroupPermissions: jsii.Boolean(false),
})
Alternatively, you can specify an ARN of an existing resource group, instead of a simple name, in your buildspec:
ts
declare const source: codebuild.Source;
// create a new ReportGroup
const reportGroup = new codebuild.ReportGroup(this, 'ReportGroup');
const project = new codebuild.Project(this, 'Project', {
source,
buildSpec: codebuild.BuildSpec.fromObject({
// ...
reports: {
[reportGroup.reportGroupArn]: {
files: '**/*',
'base-directory': 'build/test-results',
},
},
}),
});
python
# source: codebuild.Source
# create a new ReportGroup
report_group = codebuild.ReportGroup(self, "ReportGroup")
project = codebuild.Project(self, "Project",
source=source,
build_spec=codebuild.BuildSpec.from_object({
# ...
"reports": {
"report_group.report_group_arn": {
"files": "**/*",
"base-directory": "build/test-results"
}
}
})
)
java
Source source;
// create a new ReportGroup
ReportGroup reportGroup = new ReportGroup(this, "ReportGroup");
Project project = Project.Builder.create(this, "Project")
.source(source)
.buildSpec(BuildSpec.fromObject(Map.of(
// ...
"reports", Map.of(
reportGroup.getReportGroupArn(), Map.of(
"files", "**/*",
"base-directory", "build/test-results")))))
.build();
csharp
Source source;
// create a new ReportGroup
var reportGroup = new ReportGroup(this, "ReportGroup");
var project = new Project(this, "Project", new ProjectProps {
Source = source,
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
// ...
{ "reports", new Dictionary<string, IDictionary<string, string>> {
{ reportGroup.ReportGroupArn, new Struct {
Files = "**/*",
Base-directory = "build/test-results"
} }
} }
})
});
go
var source Source
// create a new ReportGroup
reportGroup := codebuild.NewReportGroup(this, jsii.String("ReportGroup"))
project := codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Source: Source,
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
// ...
"reports": map[string]map[string]*string{
reportGroup.reportGroupArn: map[string]*string{
"files": jsii.String("**/*"),
"base-directory": jsii.String("build/test-results"),
},
},
}),
})
For a code coverage report, you can specify a report group with the code coverage report group type.
ts
declare const source: codebuild.Source;
// create a new ReportGroup
const reportGroup = new codebuild.ReportGroup(this, 'ReportGroup', {
type: codebuild.ReportGroupType.CODE_COVERAGE
});
const project = new codebuild.Project(this, 'Project', {
source,
buildSpec: codebuild.BuildSpec.fromObject({
// ...
reports: {
[reportGroup.reportGroupArn]: {
files: '**/*',
'base-directory': 'build/coverage-report.xml',
'file-format': 'JACOCOXML'
},
},
}),
});
python
# source: codebuild.Source
# create a new ReportGroup
report_group = codebuild.ReportGroup(self, "ReportGroup",
type=codebuild.ReportGroupType.CODE_COVERAGE
)
project = codebuild.Project(self, "Project",
source=source,
build_spec=codebuild.BuildSpec.from_object({
# ...
"reports": {
"report_group.report_group_arn": {
"files": "**/*",
"base-directory": "build/coverage-report.xml",
"file-format": "JACOCOXML"
}
}
})
)
java
Source source;
// create a new ReportGroup
ReportGroup reportGroup = ReportGroup.Builder.create(this, "ReportGroup")
.type(ReportGroupType.CODE_COVERAGE)
.build();
Project project = Project.Builder.create(this, "Project")
.source(source)
.buildSpec(BuildSpec.fromObject(Map.of(
// ...
"reports", Map.of(
reportGroup.getReportGroupArn(), Map.of(
"files", "**/*",
"base-directory", "build/coverage-report.xml",
"file-format", "JACOCOXML")))))
.build();
csharp
Source source;
// create a new ReportGroup
var reportGroup = new ReportGroup(this, "ReportGroup", new ReportGroupProps {
Type = ReportGroupType.CODE_COVERAGE
});
var project = new Project(this, "Project", new ProjectProps {
Source = source,
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
// ...
{ "reports", new Dictionary<string, IDictionary<string, string>> {
{ reportGroup.ReportGroupArn, new Struct {
Files = "**/*",
Base-directory = "build/coverage-report.xml",
File-format = "JACOCOXML"
} }
} }
})
});
go
var source Source
// create a new ReportGroup
reportGroup := codebuild.NewReportGroup(this, jsii.String("ReportGroup"), &ReportGroupProps{
Type: codebuild.ReportGroupType_CODE_COVERAGE,
})
project := codebuild.NewProject(this, jsii.String("Project"), &ProjectProps{
Source: Source,
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
// ...
"reports": map[string]map[string]*string{
reportGroup.reportGroupArn: map[string]*string{
"files": jsii.String("**/*"),
"base-directory": jsii.String("build/coverage-report.xml"),
"file-format": jsii.String("JACOCOXML"),
},
},
}),
})
If you specify a report group, you need to grant the project's role permissions to write reports to that report group:
ts
declare const project: codebuild.Project;
declare const reportGroup: codebuild.ReportGroup;
reportGroup.grantWrite(project);
python
# project: codebuild.Project
# report_group: codebuild.ReportGroup
report_group.grant_write(project)
java
Project project;
ReportGroup reportGroup;
reportGroup.grantWrite(project);
csharp
Project project;
ReportGroup reportGroup;
reportGroup.GrantWrite(project);
go
var project Project
var reportGroup ReportGroup
reportGroup.grantWrite(project)
The created policy will adjust to the report group type. If no type is specified when creating the report group the created policy will contain the action for the test report group type.
For more information on the test reports feature, see the AWS CodeBuild documentation.
Report group deletion
When a report group is removed from a stack (or the stack is deleted), the report group will be removed according to its removal policy (which by default will simply orphan the report group and leave it in your AWS account). If the removal policy is set to RemovalPolicy.DESTROY, the report group will be deleted as long as it does not contain any reports.
To override this and force all reports to get deleted during report group deletion, enable the deleteReports option as well as setting the removal policy to RemovalPolicy.DESTROY.
ts
import * as cdk from 'aws-cdk-lib';
const reportGroup = new codebuild.ReportGroup(this, 'ReportGroup', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
deleteReports: true,
});
python
import aws_cdk as cdk
report_group = codebuild.ReportGroup(self, "ReportGroup",
removal_policy=cdk.RemovalPolicy.DESTROY,
delete_reports=True
)
java
import software.amazon.awscdk.*;
ReportGroup reportGroup = ReportGroup.Builder.create(this, "ReportGroup")
.removalPolicy(RemovalPolicy.DESTROY)
.deleteReports(true)
.build();
csharp
using Amazon.CDK;
var reportGroup = new ReportGroup(this, "ReportGroup", new ReportGroupProps {
RemovalPolicy = RemovalPolicy.DESTROY,
DeleteReports = true
});
go
import cdk "github.com/aws/aws-cdk-go/awscdk"
reportGroup := codebuild.NewReportGroup(this, jsii.String("ReportGroup"), &ReportGroupProps{
RemovalPolicy: cdk.RemovalPolicy_DESTROY,
DeleteReports: jsii.Boolean(true),
})
Events
CodeBuild projects can be used either as a source for events or be triggered by events via an event rule.
Using Project as an event target
The aws-cdk-lib/aws-events-targets.CodeBuildProject allows using an AWS CodeBuild project as a AWS CloudWatch event rule target:
ts
// start build when a commit is pushed
import * as codecommit from 'aws-cdk-lib/aws-codecommit';
import * as targets from 'aws-cdk-lib/aws-events-targets';
declare const codeCommitRepository: codecommit.Repository;
declare const project: codebuild.Project;
codeCommitRepository.onCommit('OnCommit', {
target: new targets.CodeBuildProject(project),
});
python
# start build when a commit is pushed
import aws_cdk.aws_codecommit as codecommit
import aws_cdk.aws_events_targets as targets
# code_commit_repository: codecommit.Repository
# project: codebuild.Project
code_commit_repository.on_commit("OnCommit",
target=targets.CodeBuildProject(project)
)
java
// start build when a commit is pushed
import software.amazon.awscdk.services.codecommit.*;
import software.amazon.awscdk.services.events.targets.*;
Repository codeCommitRepository;
Project project;
codeCommitRepository.onCommit("OnCommit", OnCommitOptions.builder()
.target(new CodeBuildProject(project))
.build());
csharp
// start build when a commit is pushed
using Amazon.CDK.AWS.CodeCommit;
using Amazon.CDK.AWS.Events.Targets;
Repository codeCommitRepository;
Project project;
codeCommitRepository.OnCommit("OnCommit", new OnCommitOptions {
Target = new CodeBuildProject(project)
});
go
// start build when a commit is pushed
import codecommit "github.com/aws/aws-cdk-go/awscdk"
import targets "github.com/aws/aws-cdk-go/awscdk"
var codeCommitRepository Repository
var project Project
codeCommitRepository.onCommit(jsii.String("OnCommit"), &OnCommitOptions{
Target: targets.NewCodeBuildProject(project),
})
Using Project as an event source
To define Amazon CloudWatch event rules for build projects, use one of the onXxx methods:
ts
import * as targets from 'aws-cdk-lib/aws-events-targets';
declare const fn: lambda.Function;
declare const project: codebuild.Project;
const rule = project.onStateChange('BuildStateChange', {
target: new targets.LambdaFunction(fn)
});
python
import aws_cdk.aws_events_targets as targets
# fn: lambda.Function
# project: codebuild.Project
rule = project.on_state_change("BuildStateChange",
target=targets.LambdaFunction(fn)
)
java
import software.amazon.awscdk.services.events.targets.*;
Function fn;
Project project;
Rule rule = project.onStateChange("BuildStateChange", OnEventOptions.builder()
.target(new LambdaFunction(fn))
.build());
csharp
using Amazon.CDK.AWS.Events.Targets;
Function fn;
Project project;
var rule = project.OnStateChange("BuildStateChange", new OnEventOptions {
Target = new LambdaFunction(fn)
});
go
import targets "github.com/aws/aws-cdk-go/awscdk"
var fn Function
var project Project
rule := project.onStateChange(jsii.String("BuildStateChange"), &OnEventOptions{
Target: targets.NewLambdaFunction(fn),
})
CodeStar Notifications
To define CodeStar Notification rules for Projects, use one of the notifyOnXxx() methods. They are very similar to onXxx() methods for CloudWatch events:
ts
import * as chatbot from 'aws-cdk-lib/aws-chatbot';
declare const project: codebuild.Project;
const target = new chatbot.SlackChannelConfiguration(this, 'MySlackChannel', {
slackChannelConfigurationName: 'YOUR_CHANNEL_NAME',
slackWorkspaceId: 'YOUR_SLACK_WORKSPACE_ID',
slackChannelId: 'YOUR_SLACK_CHANNEL_ID',
});
const rule = project.notifyOnBuildSucceeded('NotifyOnBuildSucceeded', target);
python
import aws_cdk.aws_chatbot as chatbot
# project: codebuild.Project
target = chatbot.SlackChannelConfiguration(self, "MySlackChannel",
slack_channel_configuration_name="YOUR_CHANNEL_NAME",
slack_workspace_id="YOUR_SLACK_WORKSPACE_ID",
slack_channel_id="YOUR_SLACK_CHANNEL_ID"
)
rule = project.notify_on_build_succeeded("NotifyOnBuildSucceeded", target)
java
import software.amazon.awscdk.services.chatbot.*;
Project project;
SlackChannelConfiguration target = SlackChannelConfiguration.Builder.create(this, "MySlackChannel")
.slackChannelConfigurationName("YOUR_CHANNEL_NAME")
.slackWorkspaceId("YOUR_SLACK_WORKSPACE_ID")
.slackChannelId("YOUR_SLACK_CHANNEL_ID")
.build();
INotificationRule rule = project.notifyOnBuildSucceeded("NotifyOnBuildSucceeded", target);
csharp
using Amazon.CDK.AWS.Chatbot;
Project project;
var target = new SlackChannelConfiguration(this, "MySlackChannel", new SlackChannelConfigurationProps {
SlackChannelConfigurationName = "YOUR_CHANNEL_NAME",
SlackWorkspaceId = "YOUR_SLACK_WORKSPACE_ID",
SlackChannelId = "YOUR_SLACK_CHANNEL_ID"
});
var rule = project.NotifyOnBuildSucceeded("NotifyOnBuildSucceeded", target);
go
import chatbot "github.com/aws/aws-cdk-go/awscdk"
var project Project
target := chatbot.NewSlackChannelConfiguration(this, jsii.String("MySlackChannel"), &SlackChannelConfigurationProps{
SlackChannelConfigurationName: jsii.String("YOUR_CHANNEL_NAME"),
SlackWorkspaceId: jsii.String("YOUR_SLACK_WORKSPACE_ID"),
SlackChannelId: jsii.String("YOUR_SLACK_CHANNEL_ID"),
})
rule := project.notifyOnBuildSucceeded(jsii.String("NotifyOnBuildSucceeded"), target)
Secondary sources and artifacts
CodeBuild Projects can get their sources from multiple places, and produce multiple outputs. For example:
ts
import * as codecommit from 'aws-cdk-lib/aws-codecommit';
declare const repo: codecommit.Repository;
declare const bucket: s3.Bucket;
const project = new codebuild.Project(this, 'MyProject', {
secondarySources: [
codebuild.Source.codeCommit({
identifier: 'source2',
repository: repo,
}),
],
secondaryArtifacts: [
codebuild.Artifacts.s3({
identifier: 'artifact2',
bucket: bucket,
path: 'some/path',
name: 'file.zip',
}),
],
// ...
});
python
import aws_cdk.aws_codecommit as codecommit
# repo: codecommit.Repository
# bucket: s3.Bucket
project = codebuild.Project(self, "MyProject",
secondary_sources=[
codebuild.Source.code_commit(
identifier="source2",
repository=repo
)
],
secondary_artifacts=[
codebuild.Artifacts.s3(
identifier="artifact2",
bucket=bucket,
path="some/path",
name="file.zip"
)
]
)
java
import software.amazon.awscdk.services.codecommit.*;
Repository repo;
Bucket bucket;
Project project = Project.Builder.create(this, "MyProject")
.secondarySources(List.of(Source.codeCommit(CodeCommitSourceProps.builder()
.identifier("source2")
.repository(repo)
.build())))
.secondaryArtifacts(List.of(Artifacts.s3(S3ArtifactsProps.builder()
.identifier("artifact2")
.bucket(bucket)
.path("some/path")
.name("file.zip")
.build())))
.build();
csharp
using Amazon.CDK.AWS.CodeCommit;
Repository repo;
Bucket bucket;
var project = new Project(this, "MyProject", new ProjectProps {
SecondarySources = new [] { Source.CodeCommit(new CodeCommitSourceProps {
Identifier = "source2",
Repository = repo
}) },
SecondaryArtifacts = new [] { Artifacts.S3(new S3ArtifactsProps {
Identifier = "artifact2",
Bucket = bucket,
Path = "some/path",
Name = "file.zip"
}) }
});
go
import codecommit "github.com/aws/aws-cdk-go/awscdk"
var repo Repository
var bucket Bucket
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
SecondarySources: []ISource{
codebuild.Source_CodeCommit(&CodeCommitSourceProps{
Identifier: jsii.String("source2"),
Repository: repo,
}),
},
SecondaryArtifacts: []IArtifacts{
codebuild.Artifacts_S3(&S3ArtifactsProps{
Identifier: jsii.String("artifact2"),
Bucket: bucket,
Path: jsii.String("some/path"),
Name: jsii.String("file.zip"),
}),
},
})
Note that the identifier property is required for both secondary sources and artifacts.
The contents of the secondary source is available to the build under the directory specified by the CODEBUILD_SRC_DIR_<identifier> environment variable (so, CODEBUILD_SRC_DIR_source2 in the above case).
The secondary artifacts have their own section in the buildspec, under the regular artifacts one. Each secondary artifact has its own section, beginning with their identifier.
So, a buildspec for the above Project could look something like this:
ts
const project = new codebuild.Project(this, 'MyProject', {
// secondary sources and artifacts as above...
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
phases: {
build: {
commands: [
'cd $CODEBUILD_SRC_DIR_source2',
'touch output2.txt',
],
},
},
artifacts: {
'secondary-artifacts': {
'artifact2': {
'base-directory': '$CODEBUILD_SRC_DIR_source2',
'files': [
'output2.txt',
],
},
},
},
}),
});
python
project = codebuild.Project(self, "MyProject",
# secondary sources and artifacts as above...
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"build": {
"commands": ["cd $CODEBUILD_SRC_DIR_source2", "touch output2.txt"
]
}
},
"artifacts": {
"secondary-artifacts": {
"artifact2": {
"base-directory": "$CODEBUILD_SRC_DIR_source2",
"files": ["output2.txt"
]
}
}
}
})
)
java
Project project = Project.Builder.create(this, "MyProject")
// secondary sources and artifacts as above...
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2",
"phases", Map.of(
"build", Map.of(
"commands", List.of("cd $CODEBUILD_SRC_DIR_source2", "touch output2.txt"))),
"artifacts", Map.of(
"secondary-artifacts", Map.of(
"artifact2", Map.of(
"base-directory", "$CODEBUILD_SRC_DIR_source2",
"files", List.of("output2.txt")))))))
.build();
csharp
var project = new Project(this, "MyProject", new ProjectProps {
// secondary sources and artifacts as above...
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" },
{ "phases", new Dictionary<string, IDictionary<string, string[]>> {
{ "build", new Struct {
Commands = new [] { "cd $CODEBUILD_SRC_DIR_source2", "touch output2.txt" }
} }
} },
{ "artifacts", new Dictionary<string, IDictionary<string, IDictionary<string, object>>> {
{ "secondary-artifacts", new Struct {
Artifact2 = new Struct {
Base-directory = "$CODEBUILD_SRC_DIR_source2",
Files = new [] { "output2.txt" }
}
} }
} }
})
});
go
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
// secondary sources and artifacts as above...
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
"phases": map[string]map[string][]*string{
"build": map[string][]*string{
"commands": []*string{
jsii.String("cd $CODEBUILD_SRC_DIR_source2"),
jsii.String("touch output2.txt"),
},
},
},
"artifacts": map[string]map[string]map[string]interface{}{
"secondary-artifacts": map[string]map[string]interface{}{
"artifact2": map[string]interface{}{
"base-directory": jsii.String("$CODEBUILD_SRC_DIR_source2"),
"files": []*string{
jsii.String("output2.txt"),
},
},
},
},
}),
})
Definition of VPC configuration in CodeBuild Project
Typically, resources in an VPC are not accessible by AWS CodeBuild. To enable access, you must provide additional VPC-specific configuration information as part of your CodeBuild project configuration. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs. VPC-enabled builds are then able to access resources inside your VPC.
For further Information see https://docs.aws.amazon.com/codebuild/latest/userguide/vpc-support.html
Use Cases VPC connectivity from AWS CodeBuild builds makes it possible to:
- Run integration tests from your build against data in an Amazon RDS database that's isolated on a private subnet.
- Query data in an Amazon ElastiCache cluster directly from tests.
- Interact with internal web services hosted on Amazon EC2, Amazon ECS, or services that use internal Elastic Load Balancing.
- Retrieve dependencies from self-hosted, internal artifact repositories, such as PyPI for Python, Maven for Java, and npm for Node.js.
- Access objects in an Amazon S3 bucket configured to allow access through an Amazon VPC endpoint only.
- Query external web services that require fixed IP addresses through the Elastic IP address of the NAT gateway or NAT instance associated with your subnet(s).
Your builds can access any resource that's hosted in your VPC.
Enable Amazon VPC Access in your CodeBuild Projects
Pass the VPC when defining your Project, then make sure to give the CodeBuild's security group the right permissions to access the resources that it needs by using the connections object.
For example:
ts
declare const loadBalancer: elbv2.ApplicationLoadBalancer;
const vpc = new ec2.Vpc(this, 'MyVPC');
const project = new codebuild.Project(this, 'MyProject', {
vpc: vpc,
buildSpec: codebuild.BuildSpec.fromObject({
// ...
}),
});
project.connections.allowTo(loadBalancer, ec2.Port.tcp(443));
python
# load_balancer: elbv2.ApplicationLoadBalancer
vpc = ec2.Vpc(self, "MyVPC")
project = codebuild.Project(self, "MyProject",
vpc=vpc,
build_spec=codebuild.BuildSpec.from_object({})
)
project.connections.allow_to(load_balancer, ec2.Port.tcp(443))
java
ApplicationLoadBalancer loadBalancer;
Vpc vpc = new Vpc(this, "MyVPC");
Project project = Project.Builder.create(this, "MyProject")
.vpc(vpc)
.buildSpec(BuildSpec.fromObject(Map.of()))
.build();
project.connections.allowTo(loadBalancer, Port.tcp(443));
csharp
ApplicationLoadBalancer loadBalancer;
var vpc = new Vpc(this, "MyVPC");
var project = new Project(this, "MyProject", new ProjectProps {
Vpc = vpc,
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> { })
});
project.Connections.AllowTo(loadBalancer, Port.Tcp(443));
go
var loadBalancer ApplicationLoadBalancer
vpc := ec2.NewVpc(this, jsii.String("MyVPC"))
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Vpc: vpc,
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
}),
})
project.connections.AllowTo(loadBalancer, ec2.Port_Tcp(jsii.Number(443)))
Project File System Location EFS
Add support for CodeBuild to build on AWS EFS file system mounts using the new ProjectFileSystemLocation. The fileSystemLocations property which accepts a list ProjectFileSystemLocation as represented by the interface IFileSystemLocations. The only supported file system type is EFS.
For example:
ts
new codebuild.Project(this, 'MyProject', {
buildSpec: codebuild.BuildSpec.fromObject({
version: '0.2',
}),
fileSystemLocations: [
codebuild.FileSystemLocation.efs({
identifier: "myidentifier2",
location: "myclodation.mydnsroot.com:/loc",
mountPoint: "/media",
mountOptions: "opts"
})
]
});
python
codebuild.Project(self, "MyProject",
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2"
}),
file_system_locations=[
codebuild.FileSystemLocation.efs(
identifier="myidentifier2",
location="myclodation.mydnsroot.com:/loc",
mount_point="/media",
mount_options="opts"
)
]
)
java
Project.Builder.create(this, "MyProject")
.buildSpec(BuildSpec.fromObject(Map.of(
"version", "0.2")))
.fileSystemLocations(List.of(FileSystemLocation.efs(EfsFileSystemLocationProps.builder()
.identifier("myidentifier2")
.location("myclodation.mydnsroot.com:/loc")
.mountPoint("/media")
.mountOptions("opts")
.build())))
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
BuildSpec = BuildSpec.FromObject(new Dictionary<string, object> {
{ "version", "0.2" }
}),
FileSystemLocations = new [] { FileSystemLocation.Efs(new EfsFileSystemLocationProps {
Identifier = "myidentifier2",
Location = "myclodation.mydnsroot.com:/loc",
MountPoint = "/media",
MountOptions = "opts"
}) }
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
BuildSpec: codebuild.BuildSpec_FromObject(map[string]interface{}{
"version": jsii.String("0.2"),
}),
FileSystemLocations: []IFileSystemLocation{
codebuild.FileSystemLocation_Efs(&EfsFileSystemLocationProps{
Identifier: jsii.String("myidentifier2"),
Location: jsii.String("myclodation.mydnsroot.com:/loc"),
MountPoint: jsii.String("/media"),
MountOptions: jsii.String("opts"),
}),
},
})
Here's a CodeBuild project with a simple example that creates a project mounted on AWS EFS:
Minimal Example
Batch builds
To enable batch builds you should call enableBatchBuilds() on the project instance.
It returns an object containing the batch service role that was created, or undefined if batch builds could not be enabled, for example if the project was imported.
ts
declare const source: codebuild.Source;
const project = new codebuild.Project(this, 'MyProject', { source, });
if (project.enableBatchBuilds()) {
console.log('Batch builds were enabled');
}
python
# source: codebuild.Source
project = codebuild.Project(self, "MyProject", source=source)
if project.enable_batch_builds():
print("Batch builds were enabled")
java
Source source;
Project project = Project.Builder.create(this, "MyProject").source(source).build();
if (project.enableBatchBuilds()) {
System.out.println("Batch builds were enabled");
}
csharp
Source source;
var project = new Project(this, "MyProject", new ProjectProps { Source = source });
if (project.EnableBatchBuilds())
{
Console.WriteLine("Batch builds were enabled");
}
go
var source Source
project := codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Source: Source,
})
if project.EnableBatchBuilds() {
fmt.Println("Batch builds were enabled")
}
Timeouts
There are two types of timeouts that can be set when creating your Project. The timeout property can be used to set an upper limit on how long your Project is able to run without being marked as completed. The default is 60 minutes. An example of overriding the default follows.
ts
new codebuild.Project(this, 'MyProject', {
timeout: Duration.minutes(90)
});
python
codebuild.Project(self, "MyProject",
timeout=Duration.minutes(90)
)
java
Project.Builder.create(this, "MyProject")
.timeout(Duration.minutes(90))
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
Timeout = Duration.Minutes(90)
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Timeout: awscdk.Duration_Minutes(jsii.Number(90)),
})
The queuedTimeout property can be used to set an upper limit on how your Project remains queued to run. There is no default value for this property. As an example, to allow your Project to queue for up to thirty (30) minutes before the build fails, use the following code.
ts
new codebuild.Project(this, 'MyProject', {
queuedTimeout: Duration.minutes(30)
});
python
codebuild.Project(self, "MyProject",
queued_timeout=Duration.minutes(30)
)
java
Project.Builder.create(this, "MyProject")
.queuedTimeout(Duration.minutes(30))
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
QueuedTimeout = Duration.Minutes(30)
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
QueuedTimeout: awscdk.Duration_Minutes(jsii.Number(30)),
})
Limiting concurrency
By default if a new build is triggered it will be run even if there is a previous build already in progress. It is possible to limit the maximum concurrent builds to value between 1 and the account specific maximum limit. By default there is no explicit limit.
ts
new codebuild.Project(this, 'MyProject', {
concurrentBuildLimit: 1
});
python
codebuild.Project(self, "MyProject",
concurrent_build_limit=1
)
java
Project.Builder.create(this, "MyProject")
.concurrentBuildLimit(1)
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
ConcurrentBuildLimit = 1
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
ConcurrentBuildLimit: jsii.Number(1),
})
Visibility
When you can specify the visibility of the project builds. This setting controls whether the builds are publicly readable or remain private.
Visibility options:
PUBLIC_READ: The project builds are visible to the public.PRIVATE: The project builds are not visible to the public.
Examples:
ts
new codebuild.Project(this, 'MyProject', {
visibility: codebuild.ProjectVisibility.PUBLIC_READ,
});
python
codebuild.Project(self, "MyProject",
visibility=codebuild.ProjectVisibility.PUBLIC_READ
)
java
Project.Builder.create(this, "MyProject")
.visibility(ProjectVisibility.PUBLIC_READ)
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
Visibility = ProjectVisibility.PUBLIC_READ
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
Visibility: codebuild.ProjectVisibility_PUBLIC_READ,
})
Auto retry limit
You can automatically retry your builds in AWS CodeBuild by setting autoRetryLimit property.
With auto-retry enabled, CodeBuild will automatically call RetryBuild using the project's service role after a failed build up to a specified limit.
For example, if the auto-retry limit is set to two, CodeBuild will call the RetryBuild API to automatically retry your build for up to two additional times.
ts
new codebuild.Project(this, 'MyProject', {
autoRetryLimit: 2,
});
python
codebuild.Project(self, "MyProject",
auto_retry_limit=2
)
java
Project.Builder.create(this, "MyProject")
.autoRetryLimit(2)
.build();
csharp
new Project(this, "MyProject", new ProjectProps {
AutoRetryLimit = 2
});
go
codebuild.NewProject(this, jsii.String("MyProject"), &ProjectProps{
AutoRetryLimit: jsii.Number(2),
})
Types
| Name | Kind | Summary |
|---|---|---|
BitBucketSourceCredentials | Construct (L2) | The source credentials used when contacting the BitBucket API. |
Fleet | Construct (L2) | Fleet for a reserved capacity CodeBuild project. |
GitHubEnterpriseSourceCredentials | Construct (L2) | The source credentials used when contacting the GitHub Enterprise API. |
GitHubSourceCredentials | Construct (L2) | The source credentials used when contacting the GitHub API. |
PipelineProject | Construct (L2) | A convenience class for CodeBuild Projects that are used in CodePipeline. |
Project | Construct (L2) | A representation of a CodeBuild Project. |
ReportGroup | Construct (L2) | The ReportGroup resource class. |
UntrustedCodeBoundaryPolicy | Construct (L2) | Permissions Boundary for a CodeBuild Project running untrusted code. |
CfnFleet | Construct (L1) | The AWS::CodeBuild::Fleet resource configures a compute fleet, a set of dedicated instances for your build environment. |
CfnProject | Construct (L1) | The AWS::CodeBuild::Project resource configures how AWS CodeBuild builds your source code. |
CfnReportGroup | Construct (L1) | Represents a report group. |
CfnSourceCredential | Construct (L1) | Information about the credentials for a GitHub, GitHub Enterprise, or Bitbucket repository. |
Artifacts | Class | Artifacts definition for a CodeBuild Project. |
ArtifactsConfig | Struct | The type returned from IArtifacts#bind. |
ArtifactsProps | Struct | Properties common to all Artifacts classes. |
BatchBuildConfig | Struct | The type returned from IProject#enableBatchBuilds. |
BindToCodePipelineOptions | Struct | The extra options passed to the IProject.bindToCodePipeline method. |
BitBucketSourceCredentialsProps | Struct | Construction properties of BitBucketSourceCredentials. |
BitBucketSourceProps | Struct | Construction properties for BitBucketSource. |
BucketCacheOptions | Struct | |
BuildEnvironment | Struct | |
BuildEnvironmentCertificate | Struct | Location of a PEM certificate on S3. |
BuildEnvironmentVariable | Struct | |
BuildEnvironmentVariableType | Enum | |
BuildImageBindOptions | Struct | Optional arguments to IBuildImage.binder - currently empty. |
BuildImageConfig | Struct | The return type from IBuildImage.binder - currently empty. |
BuildSpec | Class | BuildSpec for CodeBuild projects. |
Cache | Class | Cache options for CodeBuild Project. |
CfnFleet.ComputeConfigurationProperty | Struct | Contains compute attributes. |
CfnFleet.FleetProxyRuleProperty | Struct | Information about the proxy rule for your reserved capacity instances. |
CfnFleet.ProxyConfigurationProperty | Struct | Information about the proxy configurations that apply network access control to your reserved capacity instances. |
CfnFleet.ScalingConfigurationInputProperty | Struct | The scaling configuration input of a compute fleet. |
CfnFleet.TargetTrackingScalingConfigurationProperty | Struct | Defines when a new instance is auto-scaled into the compute fleet. |
CfnFleet.VpcConfigProperty | Struct | Information about the VPC configuration that AWS CodeBuild accesses. |
CfnFleetProps | Struct | Properties for defining a CfnFleet. |
CfnProject.ArtifactsProperty | Struct | Artifacts is a property of the AWS::CodeBuild::Project resource that specifies output settings for artifacts generated by an AWS CodeBuild build. |
CfnProject.BatchRestrictionsProperty | Struct | Specifies restrictions for the batch build. |
CfnProject.BuildStatusConfigProperty | Struct | Contains information that defines how the AWS CodeBuild build project reports the build status to the source provider. |
CfnProject.CloudWatchLogsConfigProperty | Struct | CloudWatchLogs is a property of the AWS CodeBuild Project LogsConfig property type that specifies settings for CloudWatch logs generated by an AWS CodeBuild build. |
CfnProject.DockerServerProperty | Struct | |
CfnProject.EnvironmentProperty | Struct | Environment is a property of the AWS::CodeBuild::Project resource that specifies the environment for an AWS CodeBuild project. |
CfnProject.EnvironmentVariableProperty | Struct | EnvironmentVariable is a property of the AWS CodeBuild Project Environment property type that specifies the name and value of an environment variable for an AWS CodeBuild project environment. When you use the environment to run a build, these variables are available for your builds to use. EnvironmentVariable contains a list of EnvironmentVariable property types. |
CfnProject.GitSubmodulesConfigProperty | Struct | GitSubmodulesConfig is a property of the AWS CodeBuild Project Source property type that specifies information about the Git submodules configuration for the build project. |
CfnProject.LogsConfigProperty | Struct | LogsConfig is a property of the AWS CodeBuild Project resource that specifies information about logs for a build project. These can be logs in Amazon CloudWatch Logs, built in a specified S3 bucket, or both. |
CfnProject.ProjectBuildBatchConfigProperty | Struct | Contains configuration information about a batch build project. |
CfnProject.ProjectCacheProperty | Struct | ProjectCache is a property of the AWS CodeBuild Project resource that specifies information about the cache for the build project. If ProjectCache is not specified, then both of its properties default to NO_CACHE . |
CfnProject.ProjectFileSystemLocationProperty | Struct | Information about a file system created by Amazon Elastic File System (EFS). |
CfnProject.ProjectFleetProperty | Struct | Information about the compute fleet of the build project. |
CfnProject.ProjectSourceVersionProperty | Struct | A source identifier and its corresponding version. |
CfnProject.ProjectTriggersProperty | Struct | ProjectTriggers is a property of the AWS CodeBuild Project resource that specifies webhooks that trigger an AWS CodeBuild build. |
CfnProject.PullRequestBuildPolicyProperty | Struct | |
CfnProject.RegistryCredentialProperty | Struct | RegistryCredential is a property of the AWS CodeBuild Project Environment property type that specifies information about credentials that provide access to a private Docker registry. When this is set:. |
CfnProject.S3LogsConfigProperty | Struct | S3Logs is a property of the AWS CodeBuild Project LogsConfig property type that specifies settings for logs generated by an AWS CodeBuild build in an S3 bucket. |
CfnProject.ScopeConfigurationProperty | Struct | Contains configuration information about the scope for a webhook. |
CfnProject.SourceAuthProperty | Struct | SourceAuth is a property of the AWS CodeBuild Project Source property type that specifies authorization settings for AWS CodeBuild to access the source code to be built. |
CfnProject.SourceProperty | Struct | Source is a property of the AWS::CodeBuild::Project resource that specifies the source code settings for the project, such as the source code's repository type and location. |
CfnProject.VpcConfigProperty | Struct | VpcConfig is a property of the AWS::CodeBuild::Project resource that enable AWS CodeBuild to access resources in an Amazon VPC. For more information, see Use AWS CodeBuild with Amazon Virtual Private Cloud in the AWS CodeBuild User Guide . |
CfnProject.WebhookFilterProperty | Struct | WebhookFilter is a structure of the FilterGroups property on the AWS CodeBuild Project ProjectTriggers property type that specifies which webhooks trigger an AWS CodeBuild build. |
CfnProjectProps | Struct | Properties for defining a CfnProject. |
CfnReportGroup.ReportExportConfigProperty | Struct | Information about the location where the run of a report is exported. |
CfnReportGroup.S3ReportExportConfigProperty | Struct | Information about the S3 bucket where the raw data of a report are exported. |
CfnReportGroupProps | Struct | Properties for defining a CfnReportGroup. |
CfnSourceCredentialProps | Struct | Properties for defining a CfnSourceCredential. |
CloudWatchLoggingOptions | Struct | Information about logs built to a CloudWatch Log Group for a build project. |
CodeCommitSourceProps | Struct | Construction properties for CodeCommitSource. |
CommonProjectProps | Struct | |
ComputeConfiguration | Struct | The compute configuration for the fleet. |
ComputeType | Enum | Build machine compute type. |
DockerImageOptions | Struct | The options when creating a CodeBuild Docker build image using LinuxBuildImage.fromDockerRegistry, WindowsBuildImage.fromDockerRegistry, or MacBuildImage.fromDockerRegistry. |
DockerServerComputeType | Enum | Docker server compute type. |
DockerServerOptions | Struct | The Docker server configuration CodeBuild use to build your Docker image. |
EfsFileSystemLocationProps | Struct | Construction properties for EfsFileSystemLocation. |
EnvironmentType | Enum | Build environment type. |
EventAction | Enum | The types of webhook event actions. |
FileSystemConfig | Struct | The type returned from IFileSystemLocation#bind. |
FileSystemLocation | Class | FileSystemLocation provider definition for a CodeBuild Project. |
FilterGroup | Class | An object that represents a group of filter conditions for a webhook. |
FleetComputeType | Enum | Fleet build machine compute type. Subset of Fleet compatible ComputeType values. |
FleetOverflowBehavior | Enum | The compute fleet overflow behavior. |
FleetProps | Struct | Construction properties of a CodeBuild Fleet. |
GitHubEnterpriseSourceCredentialsProps | Struct | Creation properties for GitHubEnterpriseSourceCredentials. |
GitHubEnterpriseSourceProps | Struct | Construction properties for GitHubEnterpriseSource. |
GitHubSourceCredentialsProps | Struct | Creation properties for GitHubSourceCredentials. |
GitHubSourceProps | Struct | Construction properties for GitHubSource and GitHubEnterpriseSource. |
HostKernel | Enum | The host operating system kernel used for builds in a CodeBuild project. |
IArtifacts | Interface | The abstract interface of a CodeBuild build output. |
IBindableBuildImage | Interface | A variant of IBuildImage that allows binding to the project. |
IBuildImage | Interface | Represents a Docker image used for the CodeBuild Project builds. |
IFileSystemLocation | Interface | The interface of a CodeBuild FileSystemLocation. |
IFleet | Interface | Represents a Fleet for a reserved capacity CodeBuild project. |
ImagePullPrincipalType | Enum | The type of principal CodeBuild will use to pull your build Docker image. |
IProject | Interface | |
IReportGroup | Interface | The interface representing the ReportGroup resource - either an existing one, imported using the ReportGroup.fromReportGroupName method, or a new one, created with the ReportGroup class. |
ISource | Interface | The abstract interface of a CodeBuild source. |
LinuxArmBuildImage | Class | A CodeBuild image running aarch64 Linux. |
LinuxArmLambdaBuildImage | Class | A CodeBuild image running aarch64 Lambda. |
LinuxBuildImage | Class | A CodeBuild image running x86-64 Linux. |
LinuxGpuBuildImage | Class | A CodeBuild GPU image running Linux. |
LinuxLambdaBuildImage | Class | A CodeBuild image running x86-64 Lambda. |
LocalCacheMode | Enum | Local cache modes to enable for the CodeBuild Project. |
LoggingOptions | Struct | Information about logs for the build project. |
MacBuildImage | Class | A CodeBuild image running ARM MacOS. |
MachineType | Enum | The compute type of the fleet. |
PhaseChangeEvent | Class | Event fields for the CodeBuild "phase change" event. |
PipelineProjectProps | Struct | |
ProjectNotificationEvents | Enum | The list of event types for AWS Codebuild. |
ProjectNotifyOnOptions | Struct | Additional options to pass to the notification rule. |
ProjectProps | Struct | |
ProjectVisibility | Enum | Specifies the visibility of the project's builds. |
ReportGroupProps | Struct | Construction properties for ReportGroup. |
ReportGroupType | Enum | The type of reports in the report group. |
S3ArtifactsProps | Struct | Construction properties for S3Artifacts. |
S3LoggingOptions | Struct | Information about logs built to an S3 bucket for a build project. |
S3SourceProps | Struct | Construction properties for S3Source. |
Source | Class | Source provider definition for a CodeBuild Project. |
SourceConfig | Struct | The type returned from ISource#bind. |
SourceProps | Struct | Properties common to all Source classes. |
StateChangeEvent | Class | Event fields for the CodeBuild "state change" event. |
UntrustedCodeBoundaryPolicyProps | Struct | Construction properties for UntrustedCodeBoundaryPolicy. |
WindowsBuildImage | Class | A CodeBuild image running Windows. |
WindowsImageType | Enum | Environment type for Windows Docker images. |