Language	Package
.NET	`Amazon.CDK.Pipelines`
Java	`software.amazon.awscdk.pipelines`
Python	`aws_cdk.pipelines`
TypeScript	`@aws-cdk/pipelines`

CDK Pipelines

End-of-Support

AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2.

For more information on how to migrate, see the Migrating to AWS CDK v2 guide.

A construct library for painless Continuous Delivery of CDK applications.

CDK Pipelines is an opinionated construct library. It is purpose-built to deploy one or more copies of your CDK applications using CloudFormation with a minimal amount of effort on your part. It is not intended to support arbitrary deployment pipelines, and very specifically it is not built to use CodeDeploy to applications to instances, or deploy your custom-built ECR images to an ECS cluster directly: use CDK file assets with CloudFormation Init for instances, or CDK container assets for ECS clusters instead.

Give the CDK Pipelines way of doing things a shot first: you might find it does everything you need. If you want or need more control, we recommend you drop down to using the aws-codepipeline construct library directly.

This module contains two sets of APIs: an original and a modern version of CDK Pipelines. The modern API has been updated to be easier to work with and customize, and will be the preferred API going forward. The original version of the API is still available for backwards compatibility, but we recommend migrating to the new version if possible.

Compared to the original API, the modern API: has more sensible defaults; is more flexible; supports parallel deployments; supports multiple synth inputs; allows more control of CodeBuild project generation; supports deployment engines other than CodePipeline.

The README for the original API, as well as a migration guide, can be found in our GitHub repository.

At a glance

Deploying your application continuously starts by defining a MyApplicationStage, a subclass of Stage that contains the stacks that make up a single copy of your application.

You then define a Pipeline, instantiate as many instances of MyApplicationStage as you want for your test and production environments, with different parameters for each, and calling pipeline.addStage() for each of them. You can deploy to the same account and Region, or to a different one, with the same amount of code. The CDK Pipelines library takes care of the details.

CDK Pipelines supports multiple deployment engines (see Using a different deployment engine), and comes with a deployment engine that deploys CDK apps using AWS CodePipeline. To use the CodePipeline engine, define a CodePipeline construct. The following example creates a CodePipeline that deploys an application from GitHub:

/** The stacks for our app are minimally defined here.  The internals of these
  * stacks aren't important, except that DatabaseStack exposes an attribute
  * "table" for a database table it defines, and ComputeStack accepts a reference
  * to this table in its properties.
  */
class DatabaseStack extends Stack {
  public readonly table: dynamodb.Table;

  constructor(scope: Construct, id: string) {
    super(scope, id);
    this.table = new dynamodb.Table(this, 'Table', {
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }
    });
  }
}

interface ComputeProps {
  readonly table: dynamodb.Table;
}

class ComputeStack extends Stack {
  constructor(scope: Construct, id: string, props: ComputeProps) {
    super(scope, id);
  }
}

/**
 * Stack to hold the pipeline
 */
class MyPipelineStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
      synth: new pipelines.ShellStep('Synth', {
        // Use a connection created using the AWS console to authenticate to GitHub
        // Other sources are available.
        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',
        ],
      }),
    });

    // 'MyApplication' is defined below. Call `addStage` as many times as
    // necessary with any account and region (may be different from the
    // pipeline's).
    pipeline.addStage(new MyApplication(this, 'Prod', {
      env: {
        account: '123456789012',
        region: 'eu-west-1',
      },
    }));
  }
}

/**
 * Your application
 *
 * May consist of one or more Stacks (here, two)
 *
 * By declaring our DatabaseStack and our ComputeStack inside a Stage,
 * we make sure they are deployed together, or not at all.
 */
class MyApplication extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    const dbStack = new DatabaseStack(this, 'Database');
    new ComputeStack(this, 'Compute', {
      table: dbStack.table,
    });
  }
}

// In your main file
new MyPipelineStack(this, 'PipelineStack', {
  env: {
    account: '123456789012',
    region: 'eu-west-1',
  }
});