class Project (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.AWS.CodeBuild.Project |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/awscodebuild#Project |
![]() | software.amazon.awscdk.services.codebuild.Project |
![]() | aws_cdk.aws_codebuild.Project |
![]() | aws-cdk-lib » aws_codebuild » Project |
Implements
IConstruct
, IDependable
, IResource
, IProject
, IGrantable
, IConnectable
, INotification
A representation of a CodeBuild Project.
Example
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',
},
},
// ...
})
Initializer
new Project(scope: Construct, id: string, props: ProjectProps)
Parameters
- scope
Construct
- id
string
- props
Project
Props
Construct Props
Name | Type | Description |
---|---|---|
allow | boolean | Whether to allow the CodeBuild to send all network traffic. |
artifacts? | IArtifacts | Defines where build artifacts will be stored. |
auto | number | CodeBuild will automatically call retry build using the project's service role up to the auto-retry limit. |
badge? | boolean | Indicates whether AWS CodeBuild generates a publicly accessible URL for your project's build badge. |
build | Build | Filename or contents of buildspec in JSON format. |
cache? | Cache | Caching strategy to use. |
check | boolean | 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. |
concurrent | number | Maximum number of concurrent builds. |
description? | string | A description of the project. |
encryption | IKey | Encryption key to use to read and write artifacts. |
environment? | Build | Build environment to use for the build. |
environment | { [string]: Build } | Additional environment variables to add to the build environment. |
file | IFile [] | An ProjectFileSystemLocation objects for a CodeBuild build project. |
grant | boolean | Add permissions to this project's role to create and use test report groups with name starting with the name of this project. |
logging? | Logging | Information about logs for the build project. |
project | string | The physical, human-readable name of the CodeBuild Project. |
queued | Duration | The number of minutes after which AWS CodeBuild stops the build if it's still in queue. |
role? | IRole | Service Role to assume while running the build. |
secondary | IArtifacts [] | The secondary artifacts for the Project. |
secondary | ISource [] | The secondary sources for the Project. |
security | ISecurity [] | What security group to associate with the codebuild project's network interfaces. |
source? | ISource | The source of the build. |
ssm | boolean | Add the permissions necessary for debugging builds with SSM Session Manager. |
subnet | Subnet | Where to place the network interfaces within the VPC. |
timeout? | Duration | The number of minutes after which AWS CodeBuild stops the build if it's not complete. |
visibility? | Project | Specifies the visibility of the project's builds. |
vpc? | IVpc | VPC 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.
artifacts?
Type:
IArtifacts
(optional, default: NoArtifacts)
Defines where build artifacts will be stored.
Could be: PipelineBuildArtifacts, NoArtifacts and S3Artifacts.
autoRetryLimit?
Type:
number
(optional, default: no retry)
CodeBuild will automatically call retry build using the project's service role up to the auto-retry limit.
autoRetryLimit
must be between 0 and 10.
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:
Build
(optional, default: Empty buildspec.)
Filename or contents of buildspec in JSON format.
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:
Build
(optional, default: BuildEnvironment.LinuxBuildImage.STANDARD_7_0)
Build environment to use for the build.
environmentVariables?
Type:
{ [string]:
Build
}
(optional, default: No additional environment variables are specified.)
Additional environment variables to add to the build environment.
fileSystemLocations?
Type:
IFile
[]
(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.
logging?
Type:
Logging
(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.
secondaryArtifacts?
Type:
IArtifacts
[]
(optional, default: No secondary artifacts.)
The secondary artifacts for the Project.
Can also be added after the Project has been created by using the Project#addSecondaryArtifact
method.
See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html
secondarySources?
Type:
ISource
[]
(optional, default: No secondary sources.)
The secondary sources for the Project.
Can be also added after the Project has been created by using the Project#addSecondarySource
method.
See also: https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html
securityGroups?
Type:
ISecurity
[]
(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.
source?
Type:
ISource
(optional, default: NoSource)
The source of the build.
Note: if NoSource
is given as the source,
then you need to provide an explicit buildSpec
.
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:
Subnet
(optional, default: private subnets if available else public subnets)
Where to place the network interfaces within the VPC.
To access AWS services, your CodeBuild project needs to be in one of the following types of subnets:
- Subnets with access to the internet (of type PRIVATE_WITH_EGRESS).
- Private subnets unconnected to the internet, but with VPC endpoints for the necessary services.
If you don't specify a subnet selection, the default behavior is to use PRIVATE_WITH_EGRESS subnets first if they exist, then PRIVATE_WITHOUT_EGRESS, and finally PUBLIC subnets. If your VPC doesn't have PRIVATE_WITH_EGRESS subnets but you need AWS service access, add VPC Endpoints to your private subnets.
See also: https://docs.aws.amazon.com/codebuild/latest/userguide/vpc-support.html
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.
visibility?
Type:
Project
(optional, default: no visibility is set)
Specifies the visibility of the project's builds.
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
Name | Type | Description |
---|---|---|
connections | Connections | Access the Connections object. |
env | Resource | The environment this resource belongs to. |
grant | IPrincipal | The principal to grant permissions to. |
node | Node | The tree node. |
project | string | The ARN of the project. |
project | string | The name of the project. |
stack | Stack | The stack in which this resource is defined. |
role? | IRole | The 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:
Resource
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
Name | Description |
---|---|
add | Adds a fileSystemLocation to the Project. |
add | Adds a secondary artifact to the Project. |
add | Adds a secondary source to the Project. |
add | Add a permission only if there's a policy attached. |
apply | Apply the given removal policy to this resource. |
bind | Returns a source configuration for notification rule. |
bind | A callback invoked when the given project is added to a CodePipeline. |
enable | Enable batch builds. |
metric(metricName, props?) | |
metric | Measures the number of builds triggered. |
metric | Measures the duration of all builds over time. |
metric | Measures the number of builds that failed because of client error or because of a timeout. |
metric | Measures the number of successful builds. |
notify | Defines a CodeStar Notification rule triggered when the project events emitted by you specified, it very similar to onEvent API. |
notify | Defines a CodeStar notification rule which triggers when a build fails. |
notify | Defines a CodeStar notification rule which triggers when a build completes successfully. |
on | Defines an event rule which triggers when a build fails. |
on | Defines an event rule which triggers when a build starts. |
on | Defines an event rule which triggers when a build completes successfully. |
on | Defines a CloudWatch event rule triggered when something happens with this project. |
on | Defines a CloudWatch event rule that triggers upon phase change of this build project. |
on | Defines a CloudWatch event rule triggered when the build project state changes. |
to | Returns a string representation of this construct. |
static from | |
static from | Import a Project defined either outside the CDK, or in a different CDK Stack (and exported using the export method). |
static serialize | Convert the environment variables map of string to BuildEnvironmentVariable , which is the customer-facing type, to a list of CfnProject.EnvironmentVariableProperty , which is the representation of environment variables in CloudFormation. |
addFileSystemLocation(fileSystemLocation)
public addFileSystemLocation(fileSystemLocation: IFileSystemLocation): void
Parameters
- fileSystemLocation
IFile
— the fileSystemLocation to add.System Location
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
Policy
— The permissions statement to add.Statement
Add a permission only if there's a policy attached.
applyRemovalPolicy(policy)
public applyRemovalPolicy(policy: RemovalPolicy): void
Parameters
- policy
Removal
Policy
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
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
Bind
— additional options for the binding.To Code Pipeline Options
A callback invoked when the given project is added to a CodePipeline.
enableBatchBuilds()
public enableBatchBuilds(): BatchBuildConfig
Returns
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
Metric
— Customization properties.Options
Returns
metricBuilds(props?)
public metricBuilds(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Measures the number of builds triggered.
Units: Count
Valid CloudWatch statistics: Sum
metricDuration(props?)
public metricDuration(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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
Metric
Options
Returns
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
Metric
Options
Returns
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
INotification
Rule Target - options
Project
Notify On Options
Returns
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
INotification
Rule Target - options
Notification
Rule Options
Returns
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
INotification
Rule Target - options
Notification
Rule Options
Returns
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
On
Event Options
Returns
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
On
Event Options
Returns
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
On
Event Options
Returns
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
On
Event Options
Returns
Defines a CloudWatch event rule triggered when something happens with this project.
onPhaseChange(id, options?)
public onPhaseChange(id: string, options?: OnEventOptions): Rule
Parameters
- id
string
- options
On
Event Options
Returns
Defines a CloudWatch event rule that triggers upon phase change of this build project.
onStateChange(id, options?)
public onStateChange(id: string, options?: OnEventOptions): Rule
Parameters
- id
string
- options
On
Event Options
Returns
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.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.
static fromProjectArn(scope, id, projectArn)
public static fromProjectArn(scope: Construct, id: string, projectArn: string): IProject
Parameters
- scope
Construct
- id
string
- projectArn
string
Returns
static fromProjectName(scope, id, projectName)
public static fromProjectName(scope: Construct, id: string, projectName: string): IProject
Parameters
- scope
Construct
— the parent Construct for this Construct. - id
string
— the logical name of this Construct. - projectName
string
— the name of the project to import.
Returns
Import a Project defined either outside the CDK, or in a different CDK Stack (and exported using the export
method).
static serializeEnvVariables(environmentVariables, validateNoPlainTextSecrets?, principal?)
public static serializeEnvVariables(environmentVariables: { [string]: BuildEnvironmentVariable }, validateNoPlainTextSecrets?: boolean, principal?: IGrantable): EnvironmentVariableProperty[]
Parameters
- environmentVariables
{ [string]:
Build
Environment Variable }
— the map of string to environment variables. - validateNoPlainTextSecrets
boolean
— whether to throw an exception if any of the plain text environment variables contain secrets, defaults to 'false'. - principal
IGrantable
Returns
Convert the environment variables map of string to BuildEnvironmentVariable
, which is the customer-facing type, to a list of CfnProject.EnvironmentVariableProperty
, which is the representation of environment variables in CloudFormation.