@aws-cdk/codebuild

AWS CodeBuild Construct Library

Define a project. This will also create an IAM Role and IAM Policy for CodeBuildRole to use.

Create a CodeBuild project with CodePipeline as the source:

new BuildProject(this, 'MyFirstProject', {
    source: new CodePipelineSource()
});

Create a CodeBuild project with CodeCommit as the source:

const repo = new Repository(this, 'MyRepo', { repositoryName: 'foo' });
new BuildProject(this, 'MyFirstCodeCommitProject', {
    source: new CodeCommitSource(repo)
});

Create a CodeBuild project with an S3 bucket as the source:

const bucket = new Bucket(this, 'MyBucket');
new BuildProject(this, 'MyProject', {
    source: new S3BucketSource(bucket, 'path/to/source.zip')
});

Using BuildProject as an event target

The BuildProject construct implements the IEventRuleTarget interface. This means that it can be used as a target for event rules:

// start build when a commit is pushed
codeCommitRepository.onCommit('OnCommit', buildProject);

Using BuildProject as an event source

To define CloudWatch event rules for build projects, use one of the onXxx methods:

const rule = project.onStateChange('BuildStateChange');
rule.addTarget(lambda);

Reference

BitBucketSource

class _aws-cdk_codebuild.BitBucketSource(httpsCloneUrl)

BitBucket Source definition for a CodeBuild project

Extends:BuildSource
Parameters:httpsCloneUrl (string) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty

BuildArtifacts

class _aws-cdk_codebuild.BuildArtifacts
Abstract:Yes
toArtifactsJSON() → @aws-cdk/resources.codebuild.ProjectResource.ArtifactsProperty
Return type:ArtifactsProperty
Abstract:Yes
bind(_project)
Parameters:_project (BuildProject) –

BuildEnvironment (interface)

class _aws-cdk_codebuild.BuildEnvironment
type

The type of build environment. The only allowed value is LINUX_CONTAINER.

Type:string or None
image

The Docker image identifier that the build environment uses.

Type:string or None
computeType

The type of compute to use for this build. See the ComputeType enum for options.

Type:string or None
priviledged

Indicates how the project builds Docker images. Specify true to enable running the Docker daemon inside a Docker container. This value must be set to true only if this build project will be used to build Docker images, and the specified build environment image is not one provided by AWS CodeBuild with Docker support. Otherwise, all associated builds that attempt to interact with the Docker daemon will fail.

Type:boolean or None
environmentVariables

The environment variables that your builds can use.

Type:BuildEnvironmentVariable or None

BuildEnvironmentVariable (interface)

class _aws-cdk_codebuild.BuildEnvironmentVariable
type

The type of environment variable.

Type:string or None
value

The value of the environment variable (or the name of the parameter in the SSM parameter store.)

Type:any

BuildEnvironmentVariableType (enum)

class _aws-cdk_codebuild.BuildEnvironmentVariableType
PlainText
ParameterStore

BuildProject

class _aws-cdk_codebuild.BuildProject(parent, name, props)

A CodeBuild project that is completely driven from CodePipeline (does not hot have its own input or output)

Extends:

BuildProjectRef

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (BuildProjectProps) –
addToRolePolicy(statement)

Add a permission only if there’s a policy attached.

Parameters:statement (PolicyStatement) – The permissions statement to add
role

The IAM role for this project.

Type:Role (readonly)
projectArn

The ARN of the project.

Type:ProjectArn (readonly)
projectName

The name of the project.

Type:ProjectName (readonly)

BuildProjectProps (interface)

class _aws-cdk_codebuild.BuildProjectProps
source

The source of the build.

Type:BuildSource
description

A description of the project. Use the description to identify the purpose of the project.

Type:string or None
buildSpec

Filename or contents of buildspec in JSON format.

Type:json or None
role

Service Role to assume while running the build. If not specified, a role will be created.

Type:Role or None
encryptionKey

Encryption key to use to read and write artifacts If not specified, a role will be created.

Type:EncryptionKeyRef or None
cacheBucket

Bucket to store cached source artifacts If not specified, source artifacts will not be cached.

Type:BucketRef or None
cacheDir

Subdirectory to store cached artifacts

Type:string or None
environment

Build environment to use for the build.

Type:BuildEnvironment or None
badge

Indicates whether AWS CodeBuild generates a publicly accessible URL for your project’s build badge. For more information, see Build Badges Sample in the AWS CodeBuild User Guide.

Type:boolean or None
timeout

The number of minutes after which AWS CodeBuild stops the build if it’s not complete. For valid values, see the timeoutInMinutes field in the AWS CodeBuild User Guide.

Type:number or None
artifacts

Defines where build artifacts will be stored. Could be: PipelineBuildArtifacts, NoBuildArtifacts and S3BucketBuildArtifacts.

Type:BuildArtifacts or None
environmentVariables

Additional environment variables to add to the build environment.

Type:BuildEnvironmentVariable or None

BuildProjectRef

class _aws-cdk_codebuild.BuildProjectRef(parent, name)

Represents a reference to a CodeBuild Project. If you’re managing the Project alongside the rest of your CDK resources, use the {@link BuildProject} class. If you want to reference an already existing Project (or one defined in a different CDK Stack), use the {@link import} method.

Extends:

Construct

Implements:

IEventRuleTarget

Abstract:

Yes

Parameters:
  • parent (Construct) – The parent construct
  • name (string) –
static import(parent, name, props) → @aws-cdk/codebuild.BuildProjectRef

Import a Project defined either outside the CDK, or in a different CDK Stack (and exported using the {@link export} method).

Parameters:
  • parent (Construct) – the parent Construct for this Construct
  • name (string) – the logical name of this Construct
  • props (BuildProjectRefProps) – the properties of the referenced Project
Returns:

a reference to the existing Project

Return type:

BuildProjectRef

export() → @aws-cdk/codebuild.BuildProjectRefProps

Export this Project. Allows referencing this Project in a different CDK Stack.

Return type:BuildProjectRefProps
onStateChange(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines a CloudWatch event rule triggered when the build project state changes. You can filter specific build status events using an event pattern filter on the build-status detail field: const rule = project.onStateChange(‘OnBuildStarted’, target); rule.addEventPattern({ detail: { ‘build-status’: [ “IN_PROGRESS”, “SUCCEEDED”, “FAILED”, “STOPPED” ] } }); You can also use the methods onBuildFailed and onBuildSucceeded to define rules for these specific state changes.

Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

onPhaseChange(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines a CloudWatch event rule that triggers upon phase change of this build project.

Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

onBuildStarted(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines an event rule which triggers when a build starts.

Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

onBuildFailed(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines an event rule which triggers when a build fails.

Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

onBuildSucceeded(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines an event rule which triggers when a build completes successfully.

Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

projectArn

The ARN of this Project.

Type:ProjectArn (readonly) (abstract)
projectName

The human-visible name of this Project.

Type:ProjectName (readonly) (abstract)
role

The IAM service Role of this Project. Undefined for imported Projects.

Type:Role or None (readonly) (abstract)
eventRuleTarget

Allows using build projects as event rule targets.

Type:EventRuleTarget (readonly)

BuildProjectRefProps (interface)

class _aws-cdk_codebuild.BuildProjectRefProps

Properties of a reference to a CodeBuild Project.

projectName

The human-readable name of the CodeBuild Project we’re referencing. The Project must be in the same account and region as the root Stack.

Type:ProjectName

BuildSource

class _aws-cdk_codebuild.BuildSource

Source Provider definition for a CodeBuild project TODO: Abstract class should be an interface

Abstract:Yes
bind(_project)

Called by the project when the source is added so that the source can perform binding operations on the source. For example, it can grant permissions to the code build project to read from the S3 bucket.

Parameters:_project (BuildProject) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty
Abstract:Yes

CodeCommitSource

class _aws-cdk_codebuild.CodeCommitSource(repo)

CodeCommit Source definition for a CodeBuild project

Extends:BuildSource
Parameters:repo (Repository) –
bind(project)

Called by the project when the source is added so that the source can perform binding operations on the source. For example, it can grant permissions to the code build project to read from the S3 bucket.

Parameters:project (BuildProject) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty

CodePipelineBuildArtifacts

class _aws-cdk_codebuild.CodePipelineBuildArtifacts
Extends:BuildArtifacts
toArtifactsJSON() → @aws-cdk/resources.codebuild.ProjectResource.ArtifactsProperty
Return type:ArtifactsProperty

CodePipelineSource

class _aws-cdk_codebuild.CodePipelineSource

CodePipeline Source definition for a CodeBuild project

Extends:BuildSource
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty
bind(_project)

Called by the project when the source is added so that the source can perform binding operations on the source. For example, it can grant permissions to the code build project to read from the S3 bucket.

Parameters:_project (BuildProject) –

ComputeType (enum)

class _aws-cdk_codebuild.ComputeType
Small
Medium
Large

GitHubEnterpriseSource

class _aws-cdk_codebuild.GitHubEnterpriseSource(cloneUrl)

GitHub Enterprice Source definition for a CodeBuild project

Extends:BuildSource
Parameters:cloneUrl (string) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty

GitHubSource

class _aws-cdk_codebuild.GitHubSource(httpscloneUrl, oauthToken)

GitHub Source definition for a CodeBuild project

Extends:

BuildSource

Parameters:
  • httpscloneUrl (string) –
  • oauthToken (any) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty

NoBuildArtifacts

class _aws-cdk_codebuild.NoBuildArtifacts
Extends:BuildArtifacts
toArtifactsJSON() → @aws-cdk/resources.codebuild.ProjectResource.ArtifactsProperty
Return type:ArtifactsProperty

ProjectName

class _aws-cdk_codebuild.ProjectName([valueOrFunction])
Extends:Token
Parameters:valueOrFunction (any or None) –

S3BucketBuildArtifacts

class _aws-cdk_codebuild.S3BucketBuildArtifacts(props)
Extends:BuildArtifacts
Parameters:props (S3BucketBuildArtifactsProps) –
bind(project)
Parameters:project (BuildProject) –
toArtifactsJSON() → @aws-cdk/resources.codebuild.ProjectResource.ArtifactsProperty
Return type:ArtifactsProperty

S3BucketBuildArtifactsProps (interface)

class _aws-cdk_codebuild.S3BucketBuildArtifactsProps
bucket

The name of the output bucket.

Type:BucketRef
path

The path inside of the bucket for the build output .zip file or folder. If a value is not specified, then build output will be stored at the root of the bucket (or under the <build-id> directory if includeBuildId is set to true).

Type:string or None
name

The name of the build output ZIP file or folder inside the bucket. The full S3 object key will be “<path>/build-ID/<name>” or “<path>/<artifactsName>” depending on whether includeBuildId is set to true.

Type:string
includeBuildID

Indicates if the build ID should be included in the path. If this is set to true, then the build artifact will be stored in “<path>/<build-id>/<name>”.

Type:boolean or None
packageZip

If this is true, all build output will be packaged into a single .zip file. Otherwise, all files will be uploaded to <path>/<name>

Type:boolean or None

S3BucketSource

class _aws-cdk_codebuild.S3BucketSource(bucket, path)

S3 bucket definition for a CodeBuild project.

Extends:

BuildSource

Parameters:
  • bucket (BucketRef) –
  • path (string) –
toSourceJSON() → @aws-cdk/resources.codebuild.ProjectResource.SourceProperty
Return type:SourceProperty
bind(project)

Called by the project when the source is added so that the source can perform binding operations on the source. For example, it can grant permissions to the code build project to read from the S3 bucket.

Parameters:project (BuildProject) –

SourceType (enum)

class _aws-cdk_codebuild.SourceType
CodeCommit
CodePipeline
GitHub
GitHubEnterPrise
BitBucket
S3