CodeBuildStep

class aws_cdk.pipelines.CodeBuildStep(id, *, action_role=None, build_environment=None, cache=None, file_system_locations=None, logging=None, partial_build_spec=None, project_name=None, role=None, role_policy_statements=None, security_groups=None, subnet_selection=None, timeout=None, vpc=None, commands, additional_inputs=None, env=None, env_from_cfn_outputs=None, input=None, install_commands=None, primary_output_directory=None)

Bases: ShellStep

Run a script as a CodeBuild Project.

The BuildSpec must be available inline–it cannot reference a file on disk. If your current build instructions are in a file like buildspec.yml in your repository, extract them to a script (say, build.sh) and invoke that script as part of the build:

pipelines.CodeBuildStep("Synth",
    commands=["./build.sh"]
)

ExampleMetadata:: infused

Example:

pipeline = pipelines.CodePipeline(self, "Pipeline",
    synth=pipelines.ShellStep("Synth",
        input=pipelines.CodePipelineSource.connection("my-org/my-app", "main",
            connection_arn="arn:aws:codestar-connections:us-east-1:222222222222:connection/7d2469ff-514a-4e4f-9003-5ca4a43cdc41"
        ),
        commands=["npm ci", "npm run build", "npx cdk synth"]
    ),

    # Turn this on because the pipeline uses Docker image assets
    docker_enabled_for_self_mutation=True
)

pipeline.add_wave("MyWave",
    post=[
        pipelines.CodeBuildStep("RunApproval",
            commands=["command-from-image"],
            build_environment=codebuild.BuildEnvironment(
                # The user of a Docker image asset in the pipeline requires turning on
                # 'dockerEnabledForSelfMutation'.
                build_image=codebuild.LinuxBuildImage.from_asset(self, "Image",
                    directory="./docker-image"
                )
            )
        )
    ]
)

Parameters:

id (str) – Identifier for this step.
action_role (Optional[IRole]) – Custom execution role to be used for the Code Build Action. Default: - A role is automatically created
build_environment (Union[BuildEnvironment, Dict[str, Any], None]) – Changes to environment. This environment will be combined with the pipeline’s default environment. Default: - Use the pipeline’s default build environment
cache (Optional[Cache]) – Caching strategy to use. Default: - No cache
file_system_locations (Optional[Sequence[IFileSystemLocation]]) – ProjectFileSystemLocation objects for CodeBuild build projects. 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
logging (Union[LoggingOptions, Dict[str, Any], None]) – Information about logs for CodeBuild projects. A CodeBuild project can create logs in Amazon CloudWatch Logs, an S3 bucket, or both. Default: - no log configuration is set
partial_build_spec (Optional[BuildSpec]) – Additional configuration that can only be configured via BuildSpec. You should not use this to specify output artifacts; those should be supplied via the other properties of this class, otherwise CDK Pipelines won’t be able to inspect the artifacts. Set the commands to an empty array if you want to fully specify the BuildSpec using this field. The BuildSpec must be available inline–it cannot reference a file on disk. Default: - BuildSpec completely derived from other properties
project_name (Optional[str]) – Name for the generated CodeBuild project. Default: - Automatically generated
role (Optional[IRole]) – Custom execution role to be used for the CodeBuild project. Default: - A role is automatically created
role_policy_statements (Optional[Sequence[PolicyStatement]]) – Policy statements to add to role used during the synth. Can be used to add acces to a CodeArtifact repository etc. Default: - No policy statements added to CodeBuild Project Role
security_groups (Optional[Sequence[ISecurityGroup]]) – Which security group to associate with the script’s project 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 (Union[SubnetSelection, Dict[str, Any], None]) – Which subnets to use. 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]) – The VPC where to execute the SimpleSynth. Default: - No VPC
commands (Sequence[str]) – Commands to run.
additional_inputs (Optional[Mapping[str, IFileSetProducer]]) – Additional FileSets to put in other directories. Specifies a mapping from directory name to FileSets. During the script execution, the FileSets will be available in the directories indicated. The directory names may be relative. For example, you can put the main input and an additional input side-by-side with the following configuration:: const script = new pipelines.ShellStep(‘MainScript’, { commands: [‘npm ci’,’npm run build’,’npx cdk synth’], input: pipelines.CodePipelineSource.gitHub(‘org/source1’, ‘main’), additionalInputs: { ‘../siblingdir’: pipelines.CodePipelineSource.gitHub(‘org/source2’, ‘main’), } }); Default: - No additional inputs
env (Optional[Mapping[str, str]]) – Environment variables to set. Default: - No environment variables
env_from_cfn_outputs (Optional[Mapping[str, CfnOutput]]) – Set environment variables based on Stack Outputs. ``ShellStep``s following stack or stage deployments may access the ``CfnOutput``s of those stacks to get access to –for example–automatically generated resource names or endpoint URLs. Default: - No environment variables created from stack outputs
input (Optional[IFileSetProducer]) – FileSet to run these scripts on. The files in the FileSet will be placed in the working directory when the script is executed. Use additionalInputs to download file sets to other directories as well. Default: - No input specified
install_commands (Optional[Sequence[str]]) – Installation commands to run before the regular commands. For deployment engines that support it, install commands will be classified differently in the job history from the regular commands. Default: - No installation commands
primary_output_directory (Optional[str]) – The directory that will contain the primary output fileset. After running the script, the contents of the given directory will be treated as the primary output of this Step. Default: - No primary output

Methods

add_output_directory(directory)

Add an additional output FileSet based on a directory.

After running the script, the contents of the given directory will be exported as a FileSet. Use the FileSet as the input to another step.

Multiple calls with the exact same directory name string (not normalized) will return the same FileSet.

Parameters:

directory (str) –

Return type:

FileSet

add_step_dependency(step)

Add a dependency on another step.

Parameters:

step (Step) –

Return type:

None

exported_variable(variable_name)

Reference a CodePipeline variable defined by the CodeBuildStep.

The variable must be set in the shell of the CodeBuild step when it finishes its post_build phase.

Parameters:: variable_name (str) – the name of the variable for reference.
Return type:: str

Example:

# Access the output of one CodeBuildStep in another CodeBuildStep
# pipeline: pipelines.CodePipeline


step1 = pipelines.CodeBuildStep("Step1",
    commands=["export MY_VAR=hello"]
)

step2 = pipelines.CodeBuildStep("Step2",
    env={
        "IMPORTED_VAR": step1.exported_variable("MY_VAR")
    },
    commands=["echo $IMPORTED_VAR"]
)

primary_output_directory(directory)

Configure the given output directory as primary output.

If no primary output has been configured yet, this directory will become the primary output of this ShellStep, otherwise this method will throw if the given directory is different than the currently configured primary output directory.

Parameters:

directory (str) –

Return type:

FileSet

to_string()

Return a string representation of this Step.

Return type:: str

Attributes

action_role

Custom execution role to be used for the Code Build Action.

Default:

A role is automatically created

build_environment

Build environment.

Default:

No value specified at construction time, use defaults

cache

Caching strategy to use.

Default:

No cache

commands: Commands to run.

consumed_stack_outputs: StackOutputReferences this step consumes.

dependencies: Return the steps this step depends on, based on the FileSets it requires.

dependency_file_sets: The list of FileSets consumed by this Step.

env

Environment variables to set.

Default:

No environment variables

env_from_cfn_outputs

Set environment variables based on Stack Outputs.

Default:

No environment variables created from stack outputs

file_system_locations

ProjectFileSystemLocation objects for CodeBuild build projects.

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

grant_principal: The CodeBuild Project’s principal.

id: Identifier for this step.

inputs

Input FileSets.

A list of (FileSet, directory) pairs, which are a copy of the input properties. This list should not be modified directly.

install_commands

Installation commands to run before the regular commands.

For deployment engines that support it, install commands will be classified differently in the job history from the regular commands.

Default:

No installation commands

is_source

Whether or not this is a Source step.

What it means to be a Source step depends on the engine.

logging

Information about logs for CodeBuild projects.

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

Default:

no log configuration is set

outputs

Output FileSets.

A list of (FileSet, directory) pairs, which are a copy of the input properties. This list should not be modified directly.

partial_build_spec

Additional configuration that can only be configured via BuildSpec.

Contains exported variables

Default:

Contains the exported variables

primary_output

The primary FileSet produced by this Step.

Not all steps produce an output FileSet–if they do you can substitute the Step object for the FileSet object.

project

CodeBuild Project generated for the pipeline.

Will only be available after the pipeline has been built.

project_name

Name for the generated CodeBuild project.

Default:

No value specified at construction time, use defaults

role

Custom execution role to be used for the CodeBuild project.

Default:

No value specified at construction time, use defaults

role_policy_statements

Policy statements to add to role used during the synth.

Default:

No value specified at construction time, use defaults

security_groups

Which security group to associate with the script’s project network interfaces.

Default:

No value specified at construction time, use defaults

subnet_selection

Which subnets to use.

Default:

No value specified at construction time, use defaults

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.

Default:: Duration.hours(1)

vpc

The VPC where to execute the SimpleSynth.

Default:

No value specified at construction time, use defaults

Static Methods

classmethod sequence(steps)

Define a sequence of steps to be executed in order.

If you need more fine-grained step ordering, use the addStepDependency() API. For example, if you want secondStep to occur after firstStep, call secondStep.addStepDependency(firstStep).

Parameters:

steps (Sequence[Step]) –

Return type:

List[Step]