aws-cdk-lib.aws_codebuild.PipelineProject

class PipelineProject (construct)

LanguageType name
.NETAmazon.CDK.AWS.CodeBuild.PipelineProject
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awscodebuild#PipelineProject
Javasoftware.amazon.awscdk.services.codebuild.PipelineProject
Pythonaws_cdk.aws_codebuild.PipelineProject
TypeScript (source)aws-cdk-lib » aws_codebuild » PipelineProject

Implements IConstruct, IDependable, IResource, IProject, IGrantable, IConnectable, INotificationRuleSource

A convenience class for CodeBuild Projects that are used in CodePipeline.

Example

// Create a Cloudfront Web Distribution
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
declare const distribution: cloudfront.Distribution;

// Create the build project that will invalidate the cache
const invalidateBuildProject = new codebuild.PipelineProject(this, `InvalidateProject`, {
  buildSpec: codebuild.BuildSpec.fromObject({
    version: '0.2',
    phases: {
      build: {
        commands:[
          'aws cloudfront create-invalidation --distribution-id ${CLOUDFRONT_ID} --paths "/*"',
          // Choose whatever files or paths you'd like, or all files as specified here
        ],
      },
    },
  }),
  environmentVariables: {
    CLOUDFRONT_ID: { value: distribution.distributionId },
  },
});

// Add Cloudfront invalidation permissions to the project
const distributionArn = `arn:aws:cloudfront::${this.account}:distribution/${distribution.distributionId}`;
invalidateBuildProject.addToRolePolicy(new iam.PolicyStatement({
  resources: [distributionArn],
  actions: [
    'cloudfront:CreateInvalidation',
  ],
}));

// Create the pipeline (here only the S3 deploy and Invalidate cache build)
const deployBucket = new s3.Bucket(this, 'DeployBucket');
const deployInput = new codepipeline.Artifact();
new codepipeline.Pipeline(this, 'Pipeline', {
  stages: [
    // ...
    {
      stageName: 'Deploy',
      actions: [
        new codepipeline_actions.S3DeployAction({
          actionName: 'S3Deploy',
          bucket: deployBucket,
          input: deployInput,
          runOrder: 1,
        }),
        new codepipeline_actions.CodeBuildAction({
          actionName: 'InvalidateCache',
          project: invalidateBuildProject,
          input: deployInput,
          runOrder: 2,
        }),
      ],
    },
  ],
});

Initializer

new PipelineProject(scope: Construct, id: string, props?: PipelineProjectProps)

Parameters

  • scope Construct
  • id string
  • props PipelineProjectProps

Construct Props

NameTypeDescription
allowAllOutbound?booleanWhether to allow the CodeBuild to send all network traffic.
badge?booleanIndicates whether AWS CodeBuild generates a publicly accessible URL for your project's build badge.
buildSpec?BuildSpecFilename or contents of buildspec in JSON format.
cache?CacheCaching strategy to use.
checkSecretsInPlainTextEnvVariables?booleanWhether to check for the presence of any secrets in the environment variables of the default type, BuildEnvironmentVariableType.PLAINTEXT. Since using a secret for the value of that kind of variable would result in it being displayed in plain text in the AWS Console, the construct will throw an exception if it detects a secret was passed there. Pass this property as false if you want to skip this validation, and keep using a secret in a plain text environment variable.
concurrentBuildLimit?numberMaximum number of concurrent builds.
description?stringA description of the project.
encryptionKey?IKeyEncryption key to use to read and write artifacts.
environment?BuildEnvironmentBuild environment to use for the build.
environmentVariables?{ [string]: BuildEnvironmentVariable }Additional environment variables to add to the build environment.
fileSystemLocations?IFileSystemLocation[]An ProjectFileSystemLocation objects for a CodeBuild build project.
grantReportGroupPermissions?booleanAdd permissions to this project's role to create and use test report groups with name starting with the name of this project.
logging?LoggingOptionsInformation about logs for the build project.
projectName?stringThe physical, human-readable name of the CodeBuild Project.
queuedTimeout?DurationThe number of minutes after which AWS CodeBuild stops the build if it's still in queue.
role?IRoleService Role to assume while running the build.
securityGroups?ISecurityGroup[]What security group to associate with the codebuild project's network interfaces.
ssmSessionPermissions?booleanAdd the permissions necessary for debugging builds with SSM Session Manager.
subnetSelection?SubnetSelectionWhere to place the network interfaces within the VPC.
timeout?DurationThe number of minutes after which AWS CodeBuild stops the build if it's not complete.
vpc?IVpcVPC network to place codebuild network interfaces.

allowAllOutbound?

Type: boolean (optional, default: true)

Whether to allow the CodeBuild to send all network traffic.

If set to false, you must individually add traffic rules to allow the CodeBuild project to connect to network targets.

Only used if 'vpc' is supplied.


badge?

Type: boolean (optional, default: false)

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.


buildSpec?

Type: BuildSpec (optional, default: Empty buildspec.)

Filename or contents of buildspec in JSON format.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-example


cache?

Type: Cache (optional, default: Cache.none)

Caching strategy to use.


checkSecretsInPlainTextEnvVariables?

Type: boolean (optional, default: true)

Whether to check for the presence of any secrets in the environment variables of the default type, BuildEnvironmentVariableType.PLAINTEXT. Since using a secret for the value of that kind of variable would result in it being displayed in plain text in the AWS Console, the construct will throw an exception if it detects a secret was passed there. Pass this property as false if you want to skip this validation, and keep using a secret in a plain text environment variable.


concurrentBuildLimit?

Type: number (optional, default: no explicit limit is set)

Maximum number of concurrent builds.

Minimum value is 1 and maximum is account build limit.


description?

Type: string (optional, default: No description.)

A description of the project.

Use the description to identify the purpose of the project.


encryptionKey?

Type: IKey (optional, default: The AWS-managed CMK for Amazon Simple Storage Service (Amazon S3) is used.)

Encryption key to use to read and write artifacts.


environment?

Type: BuildEnvironment (optional, default: BuildEnvironment.LinuxBuildImage.STANDARD_1_0)

Build environment to use for the build.


environmentVariables?

Type: { [string]: BuildEnvironmentVariable } (optional, default: No additional environment variables are specified.)

Additional environment variables to add to the build environment.


fileSystemLocations?

Type: IFileSystemLocation[] (optional, default: no file system locations)

An ProjectFileSystemLocation objects for a CodeBuild build project.

A ProjectFileSystemLocation object specifies the identifier, location, mountOptions, mountPoint, and type of a file system created using Amazon Elastic File System.


grantReportGroupPermissions?

Type: boolean (optional, default: true)

Add permissions to this project's role to create and use test report groups with name starting with the name of this project.

That is the standard report group that gets created when a simple name (in contrast to an ARN) is used in the 'reports' section of the buildspec of this project. This is usually harmless, but you can turn these off if you don't plan on using test reports in this project.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/test-report-group-naming.html


logging?

Type: LoggingOptions (optional, default: no log configuration is set)

Information about logs for the build project.

A project can create logs in Amazon CloudWatch Logs, an S3 bucket, or both.


projectName?

Type: string (optional, default: Name is automatically generated.)

The physical, human-readable name of the CodeBuild Project.


queuedTimeout?

Type: Duration (optional, default: no queue timeout is set)

The number of minutes after which AWS CodeBuild stops the build if it's still in queue.

For valid values, see the timeoutInMinutes field in the AWS CodeBuild User Guide.


role?

Type: IRole (optional, default: A role will be created.)

Service Role to assume while running the build.


securityGroups?

Type: ISecurityGroup[] (optional, default: Security group will be automatically created.)

What security group to associate with the codebuild project's network interfaces.

If no security group is identified, one will be created automatically.

Only used if 'vpc' is supplied.


ssmSessionPermissions?

Type: boolean (optional, default: false)

Add the permissions necessary for debugging builds with SSM Session Manager.

If the following prerequisites have been met:

  • The necessary permissions have been added by setting this flag to true.
  • The build image has the SSM agent installed (true for default CodeBuild images).
  • The build is started with debugSessionEnabled set to true.

Then the build container can be paused and inspected using Session Manager by invoking the codebuild-breakpoint command somewhere during the build.

codebuild-breakpoint commands will be ignored if the build is not started with debugSessionEnabled=true.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/session-manager.html


subnetSelection?

Type: SubnetSelection (optional, default: All private subnets.)

Where to place the network interfaces within the VPC.

Only used if 'vpc' is supplied.


timeout?

Type: Duration (optional, default: Duration.hours(1))

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.


vpc?

Type: IVpc (optional, default: No VPC is specified.)

VPC network to place codebuild network interfaces.

Specify this if the codebuild project needs to access resources in a VPC.

Properties

NameTypeDescription
connectionsConnectionsAccess the Connections object.
envResourceEnvironmentThe environment this resource belongs to.
grantPrincipalIPrincipalThe principal to grant permissions to.
nodeNodeThe tree node.
projectArnstringThe ARN of the project.
projectNamestringThe name of the project.
stackStackThe stack in which this resource is defined.
role?IRoleThe IAM role for this project.

connections

Type: Connections

Access the Connections object.

Will fail if this Project does not have a VPC set.


env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.


grantPrincipal

Type: IPrincipal

The principal to grant permissions to.


node

Type: Node

The tree node.


projectArn

Type: string

The ARN of the project.


projectName

Type: string

The name of the project.


stack

Type: Stack

The stack in which this resource is defined.


role?

Type: IRole (optional)

The IAM role for this project.

Methods

NameDescription
addFileSystemLocation(fileSystemLocation)Adds a fileSystemLocation to the Project.
addSecondaryArtifact(secondaryArtifact)Adds a secondary artifact to the Project.
addSecondarySource(secondarySource)Adds a secondary source to the Project.
addToRolePolicy(statement)Add a permission only if there's a policy attached.
applyRemovalPolicy(policy)Apply the given removal policy to this resource.
bindAsNotificationRuleSource(_scope)Returns a source configuration for notification rule.
bindToCodePipeline(_scope, options)A callback invoked when the given project is added to a CodePipeline.
enableBatchBuilds()Enable batch builds.
metric(metricName, props?)
metricBuilds(props?)Measures the number of builds triggered.
metricDuration(props?)Measures the duration of all builds over time.
metricFailedBuilds(props?)Measures the number of builds that failed because of client error or because of a timeout.
metricSucceededBuilds(props?)Measures the number of successful builds.
notifyOn(id, target, options)Defines a CodeStar Notification rule triggered when the project events emitted by you specified, it very similar to onEvent API.
notifyOnBuildFailed(id, target, options?)Defines a CodeStar notification rule which triggers when a build fails.
notifyOnBuildSucceeded(id, target, options?)Defines a CodeStar notification rule which triggers when a build completes successfully.
onBuildFailed(id, options?)Defines an event rule which triggers when a build fails.
onBuildStarted(id, options?)Defines an event rule which triggers when a build starts.
onBuildSucceeded(id, options?)Defines an event rule which triggers when a build completes successfully.
onEvent(id, options?)Defines a CloudWatch event rule triggered when something happens with this project.
onPhaseChange(id, options?)Defines a CloudWatch event rule that triggers upon phase change of this build project.
onStateChange(id, options?)Defines a CloudWatch event rule triggered when the build project state changes.
toString()Returns a string representation of this construct.

addFileSystemLocation(fileSystemLocation)

public addFileSystemLocation(fileSystemLocation: IFileSystemLocation): void

Parameters

  • fileSystemLocation IFileSystemLocation — the fileSystemLocation to add.

Adds a fileSystemLocation to the Project.


addSecondaryArtifact(secondaryArtifact)

public addSecondaryArtifact(secondaryArtifact: IArtifacts): void

Parameters

  • secondaryArtifact IArtifacts — the artifact to add as a secondary artifact.

Adds a secondary artifact to the Project.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html


addSecondarySource(secondarySource)

public addSecondarySource(secondarySource: ISource): void

Parameters

  • secondarySource ISource — the source to add as a secondary source.

Adds a secondary source to the Project.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html


addToRolePolicy(statement)

public addToRolePolicy(statement: PolicyStatement): void

Parameters

  • statement PolicyStatement — The permissions statement to add.

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


applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

  • policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).


bindAsNotificationRuleSource(_scope)

public bindAsNotificationRuleSource(_scope: Construct): NotificationRuleSourceConfig

Parameters

  • _scope Construct

Returns

  • NotificationRuleSourceConfig

Returns a source configuration for notification rule.


bindToCodePipeline(_scope, options)

public bindToCodePipeline(_scope: Construct, options: BindToCodePipelineOptions): void

Parameters

  • _scope Construct — the construct the binding is taking place in.
  • options BindToCodePipelineOptions — additional options for the binding.

A callback invoked when the given project is added to a CodePipeline.


enableBatchBuilds()

public enableBatchBuilds(): BatchBuildConfig

Returns

  • BatchBuildConfig

Enable batch builds.

Returns an object contining the batch service role if batch builds could be enabled.


metric(metricName, props?)

public metric(metricName: string, props?: MetricOptions): Metric

Parameters

  • metricName string — The name of the metric.
  • props MetricOptions — Customization properties.

Returns

  • Metric

metricBuilds(props?)

public metricBuilds(props?: MetricOptions): Metric

Parameters

  • props MetricOptions

Returns

  • Metric

Measures the number of builds triggered.

Units: Count

Valid CloudWatch statistics: Sum


metricDuration(props?)

public metricDuration(props?: MetricOptions): Metric

Parameters

  • props MetricOptions

Returns

  • Metric

Measures the duration of all builds over time.

Units: Seconds

Valid CloudWatch statistics: Average (recommended), Maximum, Minimum


metricFailedBuilds(props?)

public metricFailedBuilds(props?: MetricOptions): Metric

Parameters

  • props MetricOptions

Returns

  • Metric

Measures the number of builds that failed because of client error or because of a timeout.

Units: Count

Valid CloudWatch statistics: Sum


metricSucceededBuilds(props?)

public metricSucceededBuilds(props?: MetricOptions): Metric

Parameters

  • props MetricOptions

Returns

  • Metric

Measures the number of successful builds.

Units: Count

Valid CloudWatch statistics: Sum


notifyOn(id, target, options)

public notifyOn(id: string, target: INotificationRuleTarget, options: ProjectNotifyOnOptions): INotificationRule

Parameters

  • id string
  • target INotificationRuleTarget
  • options ProjectNotifyOnOptions

Returns

  • INotificationRule

Defines a CodeStar Notification rule triggered when the project events emitted by you specified, it very similar to onEvent API.

You can also use the methods notifyOnBuildSucceeded and notifyOnBuildFailed to define rules for these specific event emitted.


notifyOnBuildFailed(id, target, options?)

public notifyOnBuildFailed(id: string, target: INotificationRuleTarget, options?: NotificationRuleOptions): INotificationRule

Parameters

  • id string
  • target INotificationRuleTarget
  • options NotificationRuleOptions

Returns

  • INotificationRule

Defines a CodeStar notification rule which triggers when a build fails.


notifyOnBuildSucceeded(id, target, options?)

public notifyOnBuildSucceeded(id: string, target: INotificationRuleTarget, options?: NotificationRuleOptions): INotificationRule

Parameters

  • id string
  • target INotificationRuleTarget
  • options NotificationRuleOptions

Returns

  • INotificationRule

Defines a CodeStar notification rule which triggers when a build completes successfully.


onBuildFailed(id, options?)

public onBuildFailed(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

Defines an event rule which triggers when a build fails.

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.


onBuildStarted(id, options?)

public onBuildStarted(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

Defines an event rule which triggers when a build starts.

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.


onBuildSucceeded(id, options?)

public onBuildSucceeded(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

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

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.


onEvent(id, options?)

public onEvent(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

Defines a CloudWatch event rule triggered when something happens with this project.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html


onPhaseChange(id, options?)

public onPhaseChange(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

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

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html


onStateChange(id, options?)

public onStateChange(id: string, options?: OnEventOptions): Rule

Parameters

  • id string
  • options OnEventOptions

Returns

  • Rule

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.

To access fields from the event in the event target input, use the static fields on the StateChangeEvent class.

See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-build-notifications.html


toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.