class CodeBuildStep

Language	Type name
.NET	Amazon.CDK.Pipelines.CodeBuildStep
Go	github.com/aws/aws-cdk-go/awscdk/v2/pipelines#CodeBuildStep
Java	software.amazon.awscdk.pipelines.CodeBuildStep
Python	aws_cdk.pipelines.CodeBuildStep
TypeScript (source)	aws-cdk-lib » pipelines » CodeBuildStep

Implements IFileSetProducer

Extends 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:

new pipelines.CodeBuildStep('Synth', {
  commands: ['./build.sh'],
});

Example

const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
  synth: new pipelines.ShellStep('Synth', {
    input: pipelines.CodePipelineSource.connection('my-org/my-app', 'main', {
      connectionArn:
        'arn:aws:codestar-connections:us-east-1:222222222222:connection/7d2469ff-514a-4e4f-9003-5ca4a43cdc41', // Created using the AWS console * });',
    }),
    commands: ['npm ci', 'npm run build', 'npx cdk synth'],
  }),

  // Turn this on because the pipeline uses Docker image assets
  dockerEnabledForSelfMutation: true,
});

pipeline.addWave('MyWave', {
  post: [
    new pipelines.CodeBuildStep('RunApproval', {
      commands: ['command-from-image'],
      buildEnvironment: {
        // The user of a Docker image asset in the pipeline requires turning on
        // 'dockerEnabledForSelfMutation'.
        buildImage: codebuild.LinuxBuildImage.fromAsset(this, 'Image', {
          directory: './docker-image',
        }),
      },
    }),
  ],
});

Initializer

new CodeBuildStep(id: string, props: CodeBuildStepProps)

Parameters

• id string — Identifier for this step.
• props CodeBuildStepProps

Properties

Name	Type	Description
commands	string[]	Commands to run.
consumedStackOutputs	StackOutputReference[]	StackOutputReferences this step consumes.
dependencies	Step[]	Return the steps this step depends on, based on the FileSets it requires.
dependencyFileSets	FileSet[]	The list of FileSets consumed by this Step.
env	{ [string]: string }	Environment variables to set.
envFromCfnOutputs	{ [string]: StackOutputReference }	Set environment variables based on Stack Outputs.
grantPrincipal	IPrincipal	The CodeBuild Project's principal.
id	string	Identifier for this step.
inputs	FileSetLocation[]	Input FileSets.
installCommands	string[]	Installation commands to run before the regular commands.
isSource	boolean	Whether or not this is a Source step.
outputs	FileSetLocation[]	Output FileSets.
project	IProject	CodeBuild Project generated for the pipeline.
actionRole?	IRole	Custom execution role to be used for the Code Build Action.
buildEnvironment?	BuildEnvironment	Build environment.
cache?	Cache	Caching strategy to use.
fileSystemLocations?	IFileSystemLocation[]	ProjectFileSystemLocation objects for CodeBuild build projects.
logging?	LoggingOptions	Information about logs for CodeBuild projects.
partialBuildSpec?	BuildSpec	Additional configuration that can only be configured via BuildSpec.
primaryOutput?	FileSet	The primary FileSet produced by this Step.
projectName?	string	Name for the generated CodeBuild project.
role?	IRole	Custom execution role to be used for the CodeBuild project.
rolePolicyStatements?	PolicyStatement[]	Policy statements to add to role used during the synth.
securityGroups?	ISecurityGroup[]	Which security group to associate with the script's project network interfaces.
subnetSelection?	SubnetSelection	Which subnets to use.
timeout?	Duration	The number of minutes after which AWS CodeBuild stops the build if it's not complete.
vpc?	IVpc	The VPC where to execute the SimpleSynth.

---

commands

Type: string[]

Commands to run.

---

consumedStackOutputs

Type: StackOutputReference[]

StackOutputReferences this step consumes.

---

dependencies

Type: Step[]

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

---

dependencyFileSets

Type: FileSet[]

The list of FileSets consumed by this Step.

---

env

Type: { [string]: string }

Environment variables to set.

---

envFromCfnOutputs

Type: { [string]: StackOutputReference }

Set environment variables based on Stack Outputs.

---

grantPrincipal

Type: IPrincipal

The CodeBuild Project's principal.

---

id

Type: string

Identifier for this step.

---

inputs

Type: FileSetLocation[]

Input FileSets.

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

---

installCommands

Type: string[]

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.

---

isSource

Type: boolean

Whether or not this is a Source step.

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

---

outputs

Type: FileSetLocation[]

Output FileSets.

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

---

project

Type: IProject

CodeBuild Project generated for the pipeline.

Will only be available after the pipeline has been built.

---

actionRole?

Type: IRole (optional, default: A role is automatically created)

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

---

buildEnvironment?

Type: BuildEnvironment (optional, default: No value specified at construction time, use defaults)

Build environment.

---

cache?

Type: Cache (optional, default: No cache)

Caching strategy to use.

---

fileSystemLocations?

Type: IFileSystemLocation[] (optional, default: no 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.

---

logging?

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

Information about logs for CodeBuild projects.

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

---

partialBuildSpec?

Type: BuildSpec (optional, default: Contains the exported variables)

Additional configuration that can only be configured via BuildSpec.

Contains exported variables

---

primaryOutput?

Type: FileSet (optional)

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.

---

projectName?

Type: string (optional, default: No value specified at construction time, use defaults)

Name for the generated CodeBuild project.

---

role?

Type: IRole (optional, default: No value specified at construction time, use defaults)

Custom execution role to be used for the CodeBuild project.

---

rolePolicyStatements?

Type: PolicyStatement[] (optional, default: No value specified at construction time, use defaults)

Policy statements to add to role used during the synth.

---

securityGroups?

Type: ISecurityGroup[] (optional, default: No value specified at construction time, use defaults)

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

---

subnetSelection?

Type: SubnetSelection (optional, default: No value specified at construction time, use defaults)

Which subnets to use.

---

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 value specified at construction time, use defaults)

The VPC where to execute the SimpleSynth.

Methods

Name	Description
addOutputDirectory(directory)	Add an additional output FileSet based on a directory.
addStepDependency(step)	Add a dependency on another step.
exportedVariable(variableName)	Reference a CodePipeline variable defined by the CodeBuildStep.
primaryOutputDirectory(directory)	Configure the given output directory as primary output.
toString()	Return a string representation of this Step.

---

addOutputDirectory(directory)

public addOutputDirectory(directory: string): FileSet

Parameters

• directory string

Returns

• FileSet

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.

---

addStepDependency(step)

public addStepDependency(step: Step): void

Parameters

• step Step

Add a dependency on another step.

---

exportedVariable(variableName)

public exportedVariable(variableName: string): string

Parameters

• variableName string — the name of the variable for reference.

Returns

• string

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. Example

// Access the output of one CodeBuildStep in another CodeBuildStep
declare const pipeline: pipelines.CodePipeline;

const step1 = new pipelines.CodeBuildStep('Step1', {
  commands: ['export MY_VAR=hello'],
});

const step2 = new pipelines.CodeBuildStep('Step2', {
  env: {
    IMPORTED_VAR: step1.exportedVariable('MY_VAR'),
  },
  commands: ['echo $IMPORTED_VAR'],
});

---

primaryOutputDirectory(directory)

public primaryOutputDirectory(directory: string): FileSet

Parameters

• directory string

Returns

• FileSet

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.

---

toString()

public toString(): string

Returns

• string

Return a string representation of this Step.