# CodeBuildStep

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:

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

Extends: Step › ShellStep › CodeBuildStep
Implements: IFileSetProducer

- Source: [`pipelines/lib/codepipeline/codebuild-step.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/pipelines/lib/codepipeline/codebuild-step.ts#L147)
- Type last changed: v2.77.0 · 26 Apr 2023

## Example

```ts
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

```ts
new CodeBuildStep(id: string, props: CodeBuildStepProps)
```

## Properties

- `actionRole`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — Custom execution role to be used for the Code Build Action.

  **Default:** A role is automatically created

- `buildEnvironment`: [BuildEnvironment](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildEnvironment.html) — Build environment.

  **Default:** No value specified at construction time, use defaults

- `cache`: [Cache](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.Cache.html) — Caching strategy to use.

  **Default:** No cache

- `commands`: string[] — Commands to run.

- `consumedStackOutputs`: [StackOutputReference](/cdk/api/v2/docs/aws-cdk-lib.pipelines.StackOutputReference.html)[] — StackOutputReferences this step consumes.

- `dependencies`: [Step](/cdk/api/v2/docs/aws-cdk-lib.pipelines.Step.html)[] — Return the steps this step depends on, based on the FileSets it requires.

- `dependencyFileSets`: [FileSet](/cdk/api/v2/docs/aws-cdk-lib.pipelines.FileSet.html)[] — The list of FileSets consumed by this Step.

- `env`: { [key: string]: string } — Environment variables to set.

  **Default:** No environment variables

- `envFromCfnOutputs`: { [key: string]: [StackOutputReference](/cdk/api/v2/docs/aws-cdk-lib.pipelines.StackOutputReference.html) } — Set environment variables based on Stack Outputs.

  **Default:** No environment variables created from stack outputs

- `fileSystemLocations`: [IFileSystemLocation](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.IFileSystemLocation.html)[] — ProjectFileSystemLocation objects for CodeBuild build projects.

  **Default:** no file system locations

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

- `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The CodeBuild Project's principal.

- `id`: string — Identifier for this step.

- `inputs`: [FileSetLocation](/cdk/api/v2/docs/aws-cdk-lib.pipelines.FileSetLocation.html)[] — Input FileSets.

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

- `installCommands`: string[] — Installation commands to run before the regular commands.

  **Default:** No installation commands

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

- `isSource`: boolean — Whether or not this is a Source step.

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

- `logging`: [LoggingOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.LoggingOptions.html) — Information about logs for CodeBuild projects.

  **Default:** no log configuration is set

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

- `outputs`: [FileSetLocation](/cdk/api/v2/docs/aws-cdk-lib.pipelines.FileSetLocation.html)[] — Output FileSets.

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

- `partialBuildSpec`: [BuildSpec](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html) — Additional configuration that can only be configured via BuildSpec.

  **Default:** Contains the exported variables

  Contains exported variables

- `primaryOutput`: [FileSet](/cdk/api/v2/docs/aws-cdk-lib.pipelines.FileSet.html) — 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`: [IProject](/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.IProject.html) — CodeBuild Project generated for the pipeline.

  Will only be available after the pipeline has been built.

- `projectName`: string — Name for the generated CodeBuild project.

  **Default:** No value specified at construction time, use defaults

- `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — Custom execution role to be used for the CodeBuild project.

  **Default:** No value specified at construction time, use defaults

- `rolePolicyStatements`: [PolicyStatement](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html)[] — Policy statements to add to role used during the synth.

  **Default:** No value specified at construction time, use defaults

- `securityGroups`: [ISecurityGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.ISecurityGroup.html)[] — Which security group to associate with the script's project network interfaces.

  **Default:** No value specified at construction time, use defaults

- `subnetSelection`: [SubnetSelection](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetSelection.html) — Which subnets to use.

  **Default:** No value specified at construction time, use defaults

- `timeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = 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`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — The VPC where to execute the SimpleSynth.

  **Default:** No value specified at construction time, use defaults

## Methods

- `addOutputDirectory(directory: string): 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: Step): void` — Add a dependency on another step.

- `exportedVariable(variableName: string): 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.

  **Parameters**

  - `variableName` — the name of the variable for reference.

  ```ts
  // 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: string): 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.

- `sequence(steps: Step[]): Step[]` (static) — 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)`.

- `toString(): string` — Return a string representation of this Step.