@aws-cdk/aws-codepipeline

AWS CodePipeline Construct Library

---

This is a developer preview (public beta) module. Releases might lack important features and might have future breaking changes.

---

Pipeline

To construct an empty Pipeline:

import codepipeline = require('@aws-cdk/aws-codepipeline');

const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline');

To give the Pipeline a nice, human-readable name:

const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  pipelineName: 'MyPipeline',
});

Stages

You can provide Stages when creating the Pipeline:

const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  stages: [
    {
      stageName: 'Source',
      actions: [
        // see below...
      ],
    },
  ],
});

Or append a Stage to an existing Pipeline:

const sourceStage = pipeline.addStage({
  stageName: 'Source',
  actions: [ // optional property
    // see below...
  ],
});

You can insert the new Stage at an arbitrary point in the Pipeline:

const someStage = pipeline.addStage({
  stageName: 'SomeStage',
  placement: {
    // note: you can only specify one of the below properties
    rightBefore: anotherStage,
    justAfter: anotherStage,
    atIndex: 3, // indexing starts at 0
                // pipeline.stageCount returns the number of Stages currently in the Pipeline
  }
});

Actions

Actions live in a separate package, @aws-cdk/aws-codepipeline-actions.

To add an Action to a Stage, you can provide it when creating the Stage, in the actions property, or you can use the IStage.addAction() method to mutate an existing Stage:

sourceStage.addAction(someAction);

Cross-region CodePipelines

You can also use the cross-region feature to deploy resources (currently, only CloudFormation Stacks are supported) into a different region than your Pipeline is in.

It works like this:

const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
  // ...
  crossRegionReplicationBuckets: {
    // note that a physical name of the replication Bucket must be known at synthesis time
    'us-west-1': s3.Bucket.fromBucketName(this, 'UsWest1ReplicationBucket',
      'my-us-west-1-replication-bucket'),
  },
});

// later in the code...
new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  actionName: 'CFN_US_West_1',
  // ...
  region: 'us-west-1',
});

This way, the CFN_US_West_1 Action will operate in the us-west-1 region, regardless of which region your Pipeline is in.

If you don't provide a bucket for a region (other than the Pipeline's region) that you're using for an Action, there will be a new Stack, called <nameOfYourPipelineStack>-support-<region>, defined for you, containing a replication Bucket. This new Stack will depend on your Pipeline Stack, so deploying the Pipeline Stack will deploy the support Stack(s) first. Example:

$ cdk ls
MyMainStack
MyMainStack-support-us-west-1
$ cdk deploy MyMainStack
# output of cdk deploy here...

See the AWS docs here for more information on cross-region CodePipelines.

Events

Using a pipeline as an event target

A pipeline can be used as a target for a CloudWatch event rule:

// kick off the pipeline every day
const rule = new EventRule(this, 'Daily', { scheduleExpression: 'rate(1 day)' });
rule.addTarget(pipeline);

When a pipeline is used as an event target, the "codepipeline:StartPipelineExecution" permission is granted to the AWS CloudWatch Events service.

Event sources

Pipelines emit CloudWatch events. To define event rules for events emitted by the pipeline, stages or action, use the onXxx methods on the respective construct:

myPipeline.onStateChange('MyPipelineStateChage', target);
myStage.onStateChange('MyStageStateChange', target);
myAction.onStateChange('MyActioStateChange', target);

Changelog

0.37.0 (2019-07-04)

Bug Fixes

• core: fix some return types (#3192) (b5997c3)
• ecs: grant drain-hook policy container-instance permissions (#3199) (7796cd7), closes #3190
• sns: allow tokens to be used in UrlSubscription (#2938) (5ce4141)
• ssm: correctly deduplicate parameter names (#3183) (47bf435), closes #3076
• stepfunctions: Downscope SageMaker permissions (#2991) (69c82c8)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• core: construct.findChild() now only looks up direct children
• ec2: Port.toRuleJSON was renamed to toRuleJson
• codebuild: PipelineProject.addSecondaryArtifact now returns void (formerly any)
• codebuild: Project.addSecondaryArtifact now returns void (formerly any)