Project

class aws_cdk.aws_codebuild.Project(scope, id, *, artifacts=None, secondary_artifacts=None, secondary_sources=None, source=None, allow_all_outbound=None, badge=None, build_spec=None, cache=None, description=None, encryption_key=None, environment=None, environment_variables=None, file_system_locations=None, project_name=None, role=None, security_groups=None, subnet_selection=None, timeout=None, vpc=None)

Bases: aws_cdk.core.Resource

A representation of a CodeBuild Project.

__init__(scope, id, *, artifacts=None, secondary_artifacts=None, secondary_sources=None, source=None, allow_all_outbound=None, badge=None, build_spec=None, cache=None, description=None, encryption_key=None, environment=None, environment_variables=None, file_system_locations=None, project_name=None, role=None, security_groups=None, subnet_selection=None, timeout=None, vpc=None)
Parameters
  • scope (Construct) –

  • id (str) –

  • artifacts (Optional[IArtifacts]) – Defines where build artifacts will be stored. Could be: PipelineBuildArtifacts, NoArtifacts and S3Artifacts. Default: NoArtifacts

  • secondary_artifacts (Optional[List[IArtifacts]]) – The secondary artifacts for the Project. Can also be added after the Project has been created by using the {@link Project#addSecondaryArtifact} method. Default: - No secondary artifacts.

  • secondary_sources (Optional[List[ISource]]) – The secondary sources for the Project. Can be also added after the Project has been created by using the {@link Project#addSecondarySource} method. Default: - No secondary sources.

  • source (Optional[ISource]) – The source of the build. Note: if {@link NoSource} is given as the source, then you need to provide an explicit buildSpec. Default: - NoSource

  • allow_all_outbound (Optional[bool]) – 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. Default: true

  • badge (Optional[bool]) – 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. Default: false

  • build_spec (Optional[BuildSpec]) – Filename or contents of buildspec in JSON format. Default: - Empty buildspec.

  • cache (Optional[Cache]) – Caching strategy to use. Default: Cache.none

  • description (Optional[str]) – A description of the project. Use the description to identify the purpose of the project. Default: - No description.

  • encryption_key (Optional[IKey]) – Encryption key to use to read and write artifacts. Default: - The AWS-managed CMK for Amazon Simple Storage Service (Amazon S3) is used.

  • environment (Optional[BuildEnvironment]) – Build environment to use for the build. Default: BuildEnvironment.LinuxBuildImage.STANDARD_1_0

  • environment_variables (Optional[Mapping[str, BuildEnvironmentVariable]]) – Additional environment variables to add to the build environment. Default: - No additional environment variables are specified.

  • file_system_locations (Optional[List[IFileSystemLocation]]) – 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. Default: - no file system locations

  • project_name (Optional[str]) – The physical, human-readable name of the CodeBuild Project. Default: - Name is automatically generated.

  • role (Optional[IRole]) – Service Role to assume while running the build. Default: - A role will be created.

  • security_groups (Optional[List[ISecurityGroup]]) – 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. Default: - Security group will be automatically created.

  • subnet_selection (Optional[SubnetSelection]) – Where to place the network interfaces within the VPC. Only used if ‘vpc’ is supplied. Default: - All private subnets.

  • timeout (Optional[Duration]) – 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. Default: Duration.hours(1)

  • vpc (Optional[IVpc]) – VPC network to place codebuild network interfaces. Specify this if the codebuild project needs to access resources in a VPC. Default: - No VPC is specified.

Return type

None

Methods

add_file_system_location(file_system_location)

Adds a fileSystemLocation to the Project.

Parameters

file_system_location (IFileSystemLocation) – the fileSystemLocation to add.

Return type

None

add_secondary_artifact(secondary_artifact)

Adds a secondary artifact to the Project.

Parameters

secondary_artifact (IArtifacts) – the artifact to add as a secondary artifact.

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

Return type

None

add_secondary_source(secondary_source)

Adds a secondary source to the Project.

Parameters

secondary_source (ISource) – the source to add as a secondary source.

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

Return type

None

add_to_role_policy(statement)

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

Parameters

statement (PolicyStatement) – The permissions statement to add.

Return type

None

bind_to_code_pipeline(_scope, *, artifact_bucket)

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

Parameters
  • _scope (Construct) – the construct the binding is taking place in.

  • artifact_bucket (IBucket) – The artifact bucket that will be used by the action that invokes this project.

Return type

None

metric(metric_name, *, account=None, color=None, dimensions=None, label=None, period=None, region=None, statistic=None, unit=None)
Parameters
  • metric_name (str) – The name of the metric.

  • account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.

  • color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color

  • dimensions (Optional[Mapping[str, Any]]) – Dimensions of the metric. Default: - No dimensions.

  • label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. Default: - No label

  • period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)

  • region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” Default: Average

  • unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

return :rtype: Metric :return: a CloudWatch metric associated with this build project.

metric_builds(*, account=None, color=None, dimensions=None, label=None, period=None, region=None, statistic=None, unit=None)

Measures the number of builds triggered.

Units: Count

Valid CloudWatch statistics: Sum

Parameters
  • account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.

  • color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color

  • dimensions (Optional[Mapping[str, Any]]) – Dimensions of the metric. Default: - No dimensions.

  • label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. Default: - No label

  • period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)

  • region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” Default: Average

  • unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

default :default: sum over 5 minutes

Return type

Metric

metric_duration(*, account=None, color=None, dimensions=None, label=None, period=None, region=None, statistic=None, unit=None)

Measures the duration of all builds over time.

Units: Seconds

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

Parameters
  • account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.

  • color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color

  • dimensions (Optional[Mapping[str, Any]]) – Dimensions of the metric. Default: - No dimensions.

  • label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. Default: - No label

  • period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)

  • region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” Default: Average

  • unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

default :default: average over 5 minutes

Return type

Metric

metric_failed_builds(*, account=None, color=None, dimensions=None, label=None, period=None, region=None, statistic=None, unit=None)

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

Units: Count

Valid CloudWatch statistics: Sum

Parameters
  • account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.

  • color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color

  • dimensions (Optional[Mapping[str, Any]]) – Dimensions of the metric. Default: - No dimensions.

  • label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. Default: - No label

  • period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)

  • region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” Default: Average

  • unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

default :default: sum over 5 minutes

Return type

Metric

metric_succeeded_builds(*, account=None, color=None, dimensions=None, label=None, period=None, region=None, statistic=None, unit=None)

Measures the number of successful builds.

Units: Count

Valid CloudWatch statistics: Sum

Parameters
  • account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.

  • color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color

  • dimensions (Optional[Mapping[str, Any]]) – Dimensions of the metric. Default: - No dimensions.

  • label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. Default: - No label

  • period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)

  • region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” Default: Average

  • unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

default :default: sum over 5 minutes

Return type

Metric

on_build_failed(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type

Rule

on_build_started(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type

Rule

on_build_succeeded(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

Return type

Rule

on_event(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

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

Return type

Rule

on_phase_change(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

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

Return type

Rule

on_state_change(id, *, description=None, event_pattern=None, rule_name=None, target=None)

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.

Parameters
  • id (str) –

  • description (Optional[str]) – A description of the rule’s purpose. Default: - No description

  • event_pattern (Optional[EventPattern]) – Additional restrictions for the event to route to the specified target. The method that generates the rule probably imposes some type of event filtering. The filtering implied by what you pass here is added on top of that filtering. Default: - No additional filtering based on an event pattern.

  • rule_name (Optional[str]) – A name for the rule. Default: AWS CloudFormation generates a unique physical ID.

  • target (Optional[IRuleTarget]) – The target to register for the event. Default: - No target is added to the rule. Use addTarget() to add a target.

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

Return type

Rule

to_string()

Returns a string representation of this construct.

Return type

str

Attributes

connections

Access the Connections object.

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

Return type

Connections

grant_principal

The principal to grant permissions to.

Return type

IPrincipal

node

The construct tree node associated with this construct.

Return type

ConstructNode

project_arn

The ARN of the project.

Return type

str

project_name

The name of the project.

Return type

str

role

The IAM role for this project.

Return type

Optional[IRole]

stack

The stack in which this resource is defined.

Return type

Stack

Static Methods

classmethod from_project_arn(scope, id, project_arn)
Parameters
  • scope (Construct) –

  • id (str) –

  • project_arn (str) –

Return type

IProject

classmethod from_project_name(scope, id, project_name)

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

Parameters
  • scope (Construct) – the parent Construct for this Construct.

  • id (str) – the logical name of this Construct.

  • project_name (str) – the name of the project to import.

return :rtype: IProject :return: a reference to the existing Project

note: :note:

if you’re importing a CodeBuild Project for use in a CodePipeline, make sure the existing Project has permissions to access the S3 Bucket of that Pipeline - otherwise, builds in that Pipeline will always fail.

classmethod is_construct(x)

Return whether the given object is a Construct.

Parameters

x (Any) –

Return type

bool

classmethod serialize_env_variables(environment_variables)

Convert the environment variables map of string to {@link BuildEnvironmentVariable}, which is the customer-facing type, to a list of {@link CfnProject.EnvironmentVariableProperty}, which is the representation of environment variables in CloudFormation.

Parameters

environment_variables (Mapping[str, BuildEnvironmentVariable]) – the map of string to environment variables.

return :rtype: List[EnvironmentVariableProperty] :return: an array of {@link CfnProject.EnvironmentVariableProperty} instances