Package software.amazon.awscdk.services.codepipeline

package software.amazon.awscdk.services.codepipeline

AWS CodePipeline Construct Library

Pipeline

To construct an empty Pipeline: 

 // Construct an empty Pipeline
 Pipeline pipeline = new Pipeline(this, "MyFirstPipeline");

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

 // Give the Pipeline a nice, human-readable name
 Pipeline pipeline = Pipeline.Builder.create(this, "MyFirstPipeline")
         .pipelineName("MyPipeline")
         .build();

Be aware that in the default configuration, the Pipeline construct creates an AWS Key Management Service (AWS KMS) Customer Master Key (CMK) for you to encrypt the artifacts in the artifact bucket, which incurs a cost of $1/month. This default configuration is necessary to allow cross-account actions.

If you do not intend to perform cross-account deployments, you can disable the creation of the Customer Master Keys by passing crossAccountKeys: false when defining the Pipeline: 

 // Don't create Customer Master Keys
 Pipeline pipeline = Pipeline.Builder.create(this, "MyFirstPipeline")
         .crossAccountKeys(false)
         .build();

If you want to enable key rotation for the generated KMS keys, you can configure it by passing enableKeyRotation: true when creating the pipeline. Note that key rotation will incur an additional cost of $1/month. 

 // Enable key rotation for the generated KMS key
 Pipeline pipeline = Pipeline.Builder.create(this, "MyFirstPipeline")
         // ...
         .enableKeyRotation(true)
         .build();

Stages

You can provide Stages when creating the Pipeline: 

 // Provide a Stage when creating a pipeline
 Pipeline pipeline = Pipeline.Builder.create(this, "MyFirstPipeline")
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of())
                 .build()))
         .build();

Or append a Stage to an existing Pipeline: 

 // Append a Stage to an existing Pipeline
 Pipeline pipeline;
 
 IStage sourceStage = pipeline.addStage(StageOptions.builder()
         .stageName("Source")
         .actions(List.of())
         .build());

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

 // Insert a new Stage at an arbitrary point
 Pipeline pipeline;
 IStage anotherStage;
 IStage yetAnotherStage;
 
 
 IStage someStage = pipeline.addStage(StageOptions.builder()
         .stageName("SomeStage")
         .placement(StagePlacement.builder()
                 // note: you can only specify one of the below properties
                 .rightBefore(anotherStage)
                 .justAfter(yetAnotherStage)
                 .build())
         .build());

You can disable transition to a Stage: 

 // Disable transition to a stage
 Pipeline pipeline;
 
 
 IStage someStage = pipeline.addStage(StageOptions.builder()
         .stageName("SomeStage")
         .transitionToEnabled(false)
         .transitionDisabledReason("Manual transition only")
         .build());

This is useful if you don't want every executions of the pipeline to flow into this stage automatically. The transition can then be "manually" enabled later on.

Actions

Actions live in a separate package, aws-cdk-lib/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: 

 // Use the `IStage.addAction()` method to mutate an existing Stage.
 IStage sourceStage;
 Action someAction;
 
 sourceStage.addAction(someAction);

Custom Action Registration

To make your own custom CodePipeline Action requires registering the action provider. Look to the JenkinsProvider in aws-cdk-lib/aws-codepipeline-actions for an implementation example. 

 // Make a custom CodePipeline Action
 // Make a custom CodePipeline Action
 CustomActionRegistration.Builder.create(this, "GenericGitSourceProviderResource")
         .category(ActionCategory.SOURCE)
         .artifactBounds(ActionArtifactBounds.builder().minInputs(0).maxInputs(0).minOutputs(1).maxOutputs(1).build())
         .provider("GenericGitSource")
         .version("1")
         .entityUrl("https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html")
         .executionUrl("https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-custom-action.html")
         .actionProperties(List.of(CustomActionProperty.builder()
                 .name("Branch")
                 .required(true)
                 .key(false)
                 .secret(false)
                 .queryable(false)
                 .description("Git branch to pull")
                 .type("String")
                 .build(), CustomActionProperty.builder()
                 .name("GitUrl")
                 .required(true)
                 .key(false)
                 .secret(false)
                 .queryable(false)
                 .description("SSH git clone URL")
                 .type("String")
                 .build()))
         .build();

Cross-account CodePipelines

Cross-account Pipeline actions require that the Pipeline has not been created with crossAccountKeys: false.

Most pipeline Actions accept an AWS resource object to operate on. For example:

  • S3DeployAction accepts an s3.IBucket.
  • CodeBuildAction accepts a codebuild.IProject.
  • etc.

These resources can be either newly defined (new s3.Bucket(...)) or imported (s3.Bucket.fromBucketAttributes(...)) and identify the resource that should be changed.

These resources can be in different accounts than the pipeline itself. For example, the following action deploys to an imported S3 bucket from a different account: 

 // Deploy an imported S3 bucket from a different account
 IStage stage;
 Artifact input;
 
 stage.addAction(S3DeployAction.Builder.create()
         .bucket(Bucket.fromBucketAttributes(this, "Bucket", BucketAttributes.builder()
                 .account("123456789012")
                 .build()))
         .input(input)
         .actionName("s3-deploy-action")
         .build());

Actions that don't accept a resource object accept an explicit account parameter: 

 // Actions that don't accept a resource objet accept an explicit `account` parameter
 IStage stage;
 ArtifactPath templatePath;
 
 stage.addAction(CloudFormationCreateUpdateStackAction.Builder.create()
         .account("123456789012")
         .templatePath(templatePath)
         .adminPermissions(false)
         .stackName(Stack.of(this).getStackName())
         .actionName("cloudformation-create-update")
         .build());

The Pipeline construct automatically defines an IAM Role for you in the target account which the pipeline will assume to perform that action. This Role will be defined in a support stack named <PipelineStackName>-support-<account>, that will automatically be deployed before the stack containing the pipeline.

If you do not want to use the generated role, you can also explicitly pass a role when creating the action. In that case, the action will operate in the account the role belongs to: 

 // Explicitly pass in a `role` when creating an action.
 IStage stage;
 ArtifactPath templatePath;
 
 stage.addAction(CloudFormationCreateUpdateStackAction.Builder.create()
         .templatePath(templatePath)
         .adminPermissions(false)
         .stackName(Stack.of(this).getStackName())
         .actionName("cloudformation-create-update")
         // ...
         .role(Role.fromRoleArn(this, "ActionRole", "..."))
         .build());

Cross-region CodePipelines

Similar to how you set up a cross-account Action, the AWS resource object you pass to actions can also be in different Regions. For example, the following Action deploys to an imported S3 bucket from a different Region: 

 // Deploy to an imported S3 bucket from a different Region.
 IStage stage;
 Artifact input;
 
 stage.addAction(S3DeployAction.Builder.create()
         .bucket(Bucket.fromBucketAttributes(this, "Bucket", BucketAttributes.builder()
                 .region("us-west-1")
                 .build()))
         .input(input)
         .actionName("s3-deploy-action")
         .build());

Actions that don't take an AWS resource will accept an explicit region parameter: 

 // Actions that don't take an AWS resource will accept an explicit `region` parameter.
 IStage stage;
 ArtifactPath templatePath;
 
 stage.addAction(CloudFormationCreateUpdateStackAction.Builder.create()
         .templatePath(templatePath)
         .adminPermissions(false)
         .stackName(Stack.of(this).getStackName())
         .actionName("cloudformation-create-update")
         // ...
         .region("us-west-1")
         .build());

The Pipeline construct automatically defines a replication bucket for you in the target region, which the pipeline will replicate artifacts to and from. This Bucket will be defined in a support stack named <PipelineStackName>-support-<region>, that will automatically be deployed before the stack containing the pipeline.

If you don't want to use these support stacks, and already have buckets in place to serve as replication buckets, you can supply these at Pipeline definition time using the crossRegionReplicationBuckets parameter. Example: 

 // Supply replication buckets for the Pipeline instead of using the generated support stack
 Pipeline pipeline = Pipeline.Builder.create(this, "MyFirstPipeline")
         // ...
 
         .crossRegionReplicationBuckets(Map.of(
                 // note that a physical name of the replication Bucket must be known at synthesis time
                 "us-west-1", Bucket.fromBucketAttributes(this, "UsWest1ReplicationBucket", BucketAttributes.builder()
                         .bucketName("amzn-s3-demo-bucket")
                         // optional KMS key
                         .encryptionKey(Key.fromKeyArn(this, "UsWest1ReplicationKey", "arn:aws:kms:us-west-1:123456789012:key/1234-5678-9012"))
                         .build())))
         .build();

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

Creating an encrypted replication bucket

If you're passing a replication bucket created in a different stack, like this: 

 // Passing a replication bucket created in a different stack.
 App app = new App();
 Stack replicationStack = Stack.Builder.create(app, "ReplicationStack")
         .env(Environment.builder()
                 .region("us-west-1")
                 .build())
         .build();
 Key key = new Key(replicationStack, "ReplicationKey");
 Bucket replicationBucket = Bucket.Builder.create(replicationStack, "ReplicationBucket")
         // like was said above - replication buckets need a set physical name
         .bucketName(PhysicalName.GENERATE_IF_NEEDED)
         .encryptionKey(key)
         .build();
 
 // later...
 // later...
 Pipeline.Builder.create(replicationStack, "Pipeline")
         .crossRegionReplicationBuckets(Map.of(
                 "us-west-1", replicationBucket))
         .build();

When trying to encrypt it (and note that if any of the cross-region actions happen to be cross-account as well, the bucket has to be encrypted - otherwise the pipeline will fail at runtime), you cannot use a key directly - KMS keys don't have physical names, and so you can't reference them across environments.

In this case, you need to use an alias in place of the key when creating the bucket: 

 // Passing an encrypted replication bucket created in a different stack.
 App app = new App();
 Stack replicationStack = Stack.Builder.create(app, "ReplicationStack")
         .env(Environment.builder()
                 .region("us-west-1")
                 .build())
         .build();
 Key key = new Key(replicationStack, "ReplicationKey");
 Alias alias = Alias.Builder.create(replicationStack, "ReplicationAlias")
         // aliasName is required
         .aliasName(PhysicalName.GENERATE_IF_NEEDED)
         .targetKey(key)
         .build();
 Bucket replicationBucket = Bucket.Builder.create(replicationStack, "ReplicationBucket")
         .bucketName(PhysicalName.GENERATE_IF_NEEDED)
         .encryptionKey(alias)
         .build();

Variables

Variables are key-value pairs that can be used to dynamically configure actions in your pipeline.

There are two types of variables, Action-level variables and Pipeline-level variables. Action-level variables are produced when an action is executed. Pipeline-level variables are defined when the pipeline is created and resolved at pipeline run time. You specify the Pipeline-level variables when the pipeline is created, and you can provide values at the time of the pipeline execution.

Action-level variables

The library supports action-level variables. Each action class that emits variables has a separate variables interface, accessed as a property of the action instance called variables. You instantiate the action class and assign it to a local variable; when you want to use a variable in the configuration of a different action, you access the appropriate property of the interface returned from variables, which represents a single variable. Example: 

 // MyAction is some action type that produces variables, like EcrSourceAction
 MyAction myAction = new MyAction(new MyActionProps()
         // ...
         .actionName("myAction")
         );
 new OtherAction(new OtherActionProps()
         // ...
         .config(myAction.getVariables().getMyVariable())
         .actionName("otherAction")
         );

The namespace name that will be used will be automatically generated by the pipeline construct, based on the stage and action name; you can pass a custom name when creating the action instance: 

 // MyAction is some action type that produces variables, like EcrSourceAction
 MyAction myAction = new MyAction(new MyActionProps()
         // ...
         .variablesNamespace("MyNamespace")
         .actionName("myAction")
         );

There are also global variables available, not tied to any action; these are accessed through static properties of the GlobalVariables class: 

 // OtherAction is some action type that produces variables, like EcrSourceAction
 // OtherAction is some action type that produces variables, like EcrSourceAction
 new OtherAction(new OtherActionProps()
         // ...
         .config(GlobalVariables.executionId)
         .actionName("otherAction")
         );

The following is an actual code example. 

 S3SourceAction sourceAction;
 Artifact sourceOutput;
 Bucket deployBucket;
 
 
 Pipeline.Builder.create(this, "Pipeline")
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Deploy")
                 .actions(List.of(
                     S3DeployAction.Builder.create()
                             .actionName("DeployAction")
                             // can reference the variables
                             .objectKey(String.format("%s.txt", sourceAction.getVariables().getVersionId()))
                             .input(sourceOutput)
                             .bucket(deployBucket)
                             .build()))
                 .build()))
         .build();

Check the documentation of the aws-cdk-lib/aws-codepipeline-actions for details on how to use the variables for each action class.

See the CodePipeline documentation for more details on how to use the variables feature.

Pipeline-level variables

You can add one or more variables at the pipeline level. You can reference this value in the configuration of CodePipeline actions. You can add the variable names, default values, and descriptions when you create the pipeline. Variables are resolved at the time of execution.

Note that using pipeline-level variables in any kind of Source action is not supported. Also, the variables can only be used with pipeline type V2. 

 S3SourceAction sourceAction;
 Artifact sourceOutput;
 Bucket deployBucket;
 
 
 // Pipeline-level variable
 Variable variable = Variable.Builder.create()
         .variableName("bucket-var")
         .description("description")
         .defaultValue("sample")
         .build();
 
 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .variables(List.of(variable))
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Deploy")
                 .actions(List.of(
                     S3DeployAction.Builder.create()
                             .actionName("DeployAction")
                             // can reference the variables
                             .objectKey(String.format("%s.txt", variable.reference()))
                             .input(sourceOutput)
                             .bucket(deployBucket)
                             .build()))
                 .build()))
         .build();

Or append a variable to an existing pipeline: 

 Pipeline pipeline;
 
 
 Variable variable = Variable.Builder.create()
         .variableName("bucket-var")
         .description("description")
         .defaultValue("sample")
         .build();
 pipeline.addVariable(variable);

Events

Using a pipeline as an event target

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

 // A pipeline being used as a target for a CloudWatch event rule.
 import software.amazon.awscdk.services.events.targets.*;
 import software.amazon.awscdk.services.events.*;
 
 Pipeline pipeline;
 
 
 // kick off the pipeline every day
 Rule rule = Rule.Builder.create(this, "Daily")
         .schedule(Schedule.rate(Duration.days(1)))
         .build();
 rule.addTarget(new CodePipeline(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: 

 // Define event rules for events emitted by the pipeline
 import software.amazon.awscdk.services.events.*;
 
 Pipeline myPipeline;
 IStage myStage;
 Action myAction;
 IRuleTarget target;
 
 myPipeline.onStateChange("MyPipelineStateChange", OnEventOptions.builder().target(target).build());
 myStage.onStateChange("MyStageStateChange", target);
 myAction.onStateChange("MyActionStateChange", target);

CodeStar Notifications

To define CodeStar Notification rules for Pipelines, use one of the notifyOnXxx() methods. They are very similar to onXxx() methods for CloudWatch events: 

 // Define CodeStar Notification rules for Pipelines
 import software.amazon.awscdk.services.chatbot.*;
 
 Pipeline pipeline;
 
 SlackChannelConfiguration target = SlackChannelConfiguration.Builder.create(this, "MySlackChannel")
         .slackChannelConfigurationName("YOUR_CHANNEL_NAME")
         .slackWorkspaceId("YOUR_SLACK_WORKSPACE_ID")
         .slackChannelId("YOUR_SLACK_CHANNEL_ID")
         .build();
 INotificationRule rule = pipeline.notifyOnExecutionStateChange("NotifyOnExecutionStateChange", target);

Trigger

To trigger a pipeline with Git tags or branches, specify the triggers property. The triggers can only be used with pipeline type V2.

Push filter

Pipelines can be started based on push events. You can specify the pushFilter property to filter the push events. The pushFilter can specify Git tags.

In the case of Git tags, your pipeline starts when a Git tag is pushed. You can filter with glob patterns. The tagsExcludes takes priority over the tagsIncludes. 

 CodeStarConnectionsSourceAction sourceAction;
 CodeBuildAction buildAction;
 
 
 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Build")
                 .actions(List.of(buildAction))
                 .build()))
         .triggers(List.of(TriggerProps.builder()
                 .providerType(ProviderType.CODE_STAR_SOURCE_CONNECTION)
                 .gitConfiguration(GitConfiguration.builder()
                         .sourceAction(sourceAction)
                         .pushFilter(List.of(GitPushFilter.builder()
                                 .tagsExcludes(List.of("exclude1", "exclude2"))
                                 .tagsIncludes(List.of("include*"))
                                 .build()))
                         .build())
                 .build()))
         .build();

Pull request filter

Pipelines can be started based on pull request events. You can specify the pullRequestFilter property to filter the pull request events. The pullRequestFilter can specify branches, file paths, and event types.

In the case of branches, your pipeline starts when a pull request event occurs on the specified branches. You can filter with glob patterns. The branchesExcludes takes priority over the branchesIncludes. 

 CodeStarConnectionsSourceAction sourceAction;
 CodeBuildAction buildAction;
 
 
 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Build")
                 .actions(List.of(buildAction))
                 .build()))
         .triggers(List.of(TriggerProps.builder()
                 .providerType(ProviderType.CODE_STAR_SOURCE_CONNECTION)
                 .gitConfiguration(GitConfiguration.builder()
                         .sourceAction(sourceAction)
                         .pullRequestFilter(List.of(GitPullRequestFilter.builder()
                                 .branchesExcludes(List.of("exclude1", "exclude2"))
                                 .branchesIncludes(List.of("include*"))
                                 .build()))
                         .build())
                 .build()))
         .build();

File paths can also be specified along with the branches to start the pipeline. You can filter with glob patterns. The filePathsExcludes takes priority over the filePathsIncludes. 

 CodeStarConnectionsSourceAction sourceAction;
 CodeBuildAction buildAction;
 
 
 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Build")
                 .actions(List.of(buildAction))
                 .build()))
         .triggers(List.of(TriggerProps.builder()
                 .providerType(ProviderType.CODE_STAR_SOURCE_CONNECTION)
                 .gitConfiguration(GitConfiguration.builder()
                         .sourceAction(sourceAction)
                         .pullRequestFilter(List.of(GitPullRequestFilter.builder()
                                 .branchesExcludes(List.of("exclude1", "exclude2"))
                                 .branchesIncludes(List.of("include1", "include2"))
                                 .filePathsExcludes(List.of("/path/to/exclude1", "/path/to/exclude2"))
                                 .filePathsIncludes(List.of("/path/to/include1", "/path/to/include1"))
                                 .build()))
                         .build())
                 .build()))
         .build();

To filter types of pull request events for triggers, you can specify the events property. 

 CodeStarConnectionsSourceAction sourceAction;
 CodeBuildAction buildAction;
 
 
 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .stages(List.of(StageProps.builder()
                 .stageName("Source")
                 .actions(List.of(sourceAction))
                 .build(), StageProps.builder()
                 .stageName("Build")
                 .actions(List.of(buildAction))
                 .build()))
         .triggers(List.of(TriggerProps.builder()
                 .providerType(ProviderType.CODE_STAR_SOURCE_CONNECTION)
                 .gitConfiguration(GitConfiguration.builder()
                         .sourceAction(sourceAction)
                         .pullRequestFilter(List.of(GitPullRequestFilter.builder()
                                 .branchesExcludes(List.of("exclude1", "exclude2"))
                                 .branchesIncludes(List.of("include1", "include2"))
                                 .events(List.of(GitPullRequestEvent.OPEN, GitPullRequestEvent.CLOSED))
                                 .build()))
                         .build())
                 .build()))
         .build();

Append a trigger to an existing pipeline

You can append a trigger to an existing pipeline: 

 Pipeline pipeline;
 CodeStarConnectionsSourceAction sourceAction;
 
 
 pipeline.addTrigger(TriggerProps.builder()
         .providerType(ProviderType.CODE_STAR_SOURCE_CONNECTION)
         .gitConfiguration(GitConfiguration.builder()
                 .sourceAction(sourceAction)
                 .pushFilter(List.of(GitPushFilter.builder()
                         .tagsExcludes(List.of("exclude1", "exclude2"))
                         .tagsIncludes(List.of("include*"))
                         .build()))
                 .build())
         .build());

Execution mode

To control the concurrency behavior when multiple executions of a pipeline are started, you can use the executionMode property.

The execution mode can only be used with pipeline type V2. 

 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .executionMode(ExecutionMode.PARALLEL)
         .build();

Migrating a pipeline type from V1 to V2

To migrate your pipeline type from V1 to V2, you just need to update the pipelineType property to PipelineType.V2. This migration does not cause replacement of your pipeline.

When the @aws-cdk/aws-codepipeline:defaultPipelineTypeToV2 feature flag is set to true (default for new projects), the V2 type is selected by default if you do not specify a value for pipelineType property. Otherwise, the V1 type is selected. 

 Pipeline.Builder.create(this, "Pipeline")
         .pipelineType(PipelineType.V2)
         .build();

See the CodePipeline documentation for more details on the differences between each type.