Show / Hide Table of Contents

Namespace Amazon.CDK.AWS.CodePipeline

AWS CodePipeline Construct Library

--- cfn-resources: Stable cdk-constructs: Stable

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 = new Pipeline(this, "MyFirstPipeline", new PipelineProps {
    PipelineName = "MyPipeline"
});

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 = new Pipeline(this, "MyFirstPipeline", new PipelineProps {
    CrossAccountKeys = false
});

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 = new Pipeline(this, "MyFirstPipeline", new PipelineProps {
    // ...
    EnableKeyRotation = true
});

Stages

You can provide Stages when creating the Pipeline:

// Provide a Stage when creating a pipeline
Pipeline pipeline = new Pipeline(this, "MyFirstPipeline", new PipelineProps {
    Stages = new [] { new StageProps {
        StageName = "Source",
        Actions = new [] {  }
    } }
});

Or append a Stage to an existing Pipeline:

// Append a Stage to an existing Pipeline
Pipeline pipeline;

IStage sourceStage = pipeline.AddStage(new StageOptions {
    StageName = "Source",
    Actions = new [] {  }
});

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(new StageOptions {
    StageName = "SomeStage",
    Placement = new StagePlacement {
        // note: you can only specify one of the below properties
        RightBefore = anotherStage,
        JustAfter = yetAnotherStage
    }
});

You can disable transition to a Stage:

// Disable transition to a stage
Pipeline pipeline;


IStage someStage = pipeline.AddStage(new StageOptions {
    StageName = "SomeStage",
    TransitionToEnabled = false,
    TransitionDisabledReason = "Manual transition only"
});

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/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/aws-codepipeline-actions for an implementation example.

// Make a custom CodePipeline Action
// Make a custom CodePipeline Action
new CustomActionRegistration(this, "GenericGitSourceProviderResource", new CustomActionRegistrationProps {
    Category = ActionCategory.SOURCE,
    ArtifactBounds = new ActionArtifactBounds { MinInputs = 0, MaxInputs = 0, MinOutputs = 1, MaxOutputs = 1 },
    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 = new [] { new CustomActionProperty {
        Name = "Branch",
        Required = true,
        Key = false,
        Secret = false,
        Queryable = false,
        Description = "Git branch to pull",
        Type = "String"
    }, new CustomActionProperty {
        Name = "GitUrl",
        Required = true,
        Key = false,
        Secret = false,
        Queryable = false,
        Description = "SSH git clone URL",
        Type = "String"
    } }
});

Cross-account CodePipelines

Cross-account Pipeline actions require that the Pipeline has <em>not</em> been
created with <code>crossAccountKeys: false</code>.

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

    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(new S3DeployAction(new S3DeployActionProps {
        Bucket = Bucket.FromBucketAttributes(this, "Bucket", new BucketAttributes {
            Account = "123456789012"
        }),
        Input = input,
        ActionName = "s3-deploy-action"
    }));

    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(new CloudFormationCreateUpdateStackAction(new CloudFormationCreateUpdateStackActionProps {
        Account = "123456789012",
        TemplatePath = templatePath,
        AdminPermissions = false,
        StackName = Stack.Of(this).StackName,
        ActionName = "cloudformation-create-update"
    }));

    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(new CloudFormationCreateUpdateStackAction(new CloudFormationCreateUpdateStackActionProps {
        TemplatePath = templatePath,
        AdminPermissions = false,
        StackName = Stack.Of(this).StackName,
        ActionName = "cloudformation-create-update",
        // ...
        Role = Role.FromRoleArn(this, "ActionRole", "...")
    }));

    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(new S3DeployAction(new S3DeployActionProps {
        Bucket = Bucket.FromBucketAttributes(this, "Bucket", new BucketAttributes {
            Region = "us-west-1"
        }),
        Input = input,
        ActionName = "s3-deploy-action"
    }));

    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(new CloudFormationCreateUpdateStackAction(new CloudFormationCreateUpdateStackActionProps {
        TemplatePath = templatePath,
        AdminPermissions = false,
        StackName = Stack.Of(this).StackName,
        ActionName = "cloudformation-create-update",
        // ...
        Region = "us-west-1"
    }));

    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 = new Pipeline(this, "MyFirstPipeline", new PipelineProps {
        // ...
    
        CrossRegionReplicationBuckets = new Dictionary<string, IBucket> {
            // note that a physical name of the replication Bucket must be known at synthesis time
            { "us-west-1", Bucket.FromBucketAttributes(this, "UsWest1ReplicationBucket", new BucketAttributes {
                BucketName = "my-us-west-1-replication-bucket",
                // optional KMS key
                EncryptionKey = Key.FromKeyArn(this, "UsWest1ReplicationKey", "arn:aws:kms:us-west-1:123456789012:key/1234-5678-9012")
            }) }
        }
    });

    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 = new Stack(app, "ReplicationStack", new StackProps {
        Env = new Environment {
            Region = "us-west-1"
        }
    });
    Key key = new Key(replicationStack, "ReplicationKey");
    Bucket replicationBucket = new Bucket(replicationStack, "ReplicationBucket", new BucketProps {
        // like was said above - replication buckets need a set physical name
        BucketName = PhysicalName.GENERATE_IF_NEEDED,
        EncryptionKey = key
    });
    
    // later...
    // later...
    new Pipeline(replicationStack, "Pipeline", new PipelineProps {
        CrossRegionReplicationBuckets = new Dictionary<string, IBucket> {
            { "us-west-1", replicationBucket }
        }
    });

    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 = new Stack(app, "ReplicationStack", new StackProps {
        Env = new Environment {
            Region = "us-west-1"
        }
    });
    Key key = new Key(replicationStack, "ReplicationKey");
    Alias alias = new Alias(replicationStack, "ReplicationAlias", new AliasProps {
        // aliasName is required
        AliasName = PhysicalName.GENERATE_IF_NEEDED,
        TargetKey = key
    });
    Bucket replicationBucket = new Bucket(replicationStack, "ReplicationBucket", new BucketProps {
        BucketName = PhysicalName.GENERATE_IF_NEEDED,
        EncryptionKey = alias
    });

    Variables

    The library supports the CodePipeline Variables feature. 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.Variables.MyVariable,
        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"
    });

    Check the documentation of the @aws-cdk/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.

    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.
    using Amazon.CDK.AWS.Events.Targets;
    using Amazon.CDK.AWS.Events;
    
    Pipeline pipeline;
    
    
    // kick off the pipeline every day
    Rule rule = new Rule(this, "Daily", new RuleProps {
        Schedule = Schedule.Rate(Duration.Days(1))
    });
    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
    using Amazon.CDK.AWS.Events;
    
    Pipeline myPipeline;
    IStage myStage;
    Action myAction;
    IRuleTarget target;
    
    myPipeline.OnStateChange("MyPipelineStateChange", new OnEventOptions { Target = target });
    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
    using Amazon.CDK.AWS.Chatbot;
    
    Pipeline pipeline;
    
    SlackChannelConfiguration target = new SlackChannelConfiguration(this, "MySlackChannel", new SlackChannelConfigurationProps {
        SlackChannelConfigurationName = "YOUR_CHANNEL_NAME",
        SlackWorkspaceId = "YOUR_SLACK_WORKSPACE_ID",
        SlackChannelId = "YOUR_SLACK_CHANNEL_ID"
    });
    INotificationRule rule = pipeline.NotifyOnExecutionStateChange("NotifyOnExecutionStateChange", target);

    Classes

    Action

    Low-level class for generic CodePipeline Actions implementing the {@link IAction} interface.

    ActionArtifactBounds

    Specifies the constraints on the number of input and output artifacts an action can have.

    ActionBindOptions
    ActionCategory
    ActionConfig
    ActionProperties
    Artifact_

    An output artifact of an action.

    ArtifactPath_

    A specific file within an output artifact.

    CfnCustomActionType

    A CloudFormation AWS::CodePipeline::CustomActionType.

    CfnCustomActionType.ArtifactDetailsProperty

    Returns information about the details of an artifact.

    CfnCustomActionType.ConfigurationPropertiesProperty

    The configuration properties for the custom action.

    CfnCustomActionType.SettingsProperty

    Settings is a property of the AWS::CodePipeline::CustomActionType resource that provides URLs that users can access to view information about the CodePipeline custom action.

    CfnCustomActionTypeProps

    Properties for defining a CfnCustomActionType.

    CfnPipeline

    A CloudFormation AWS::CodePipeline::Pipeline.

    CfnPipeline.ActionDeclarationProperty

    Represents information about an action declaration.

    CfnPipeline.ActionTypeIdProperty

    Represents information about an action type.

    CfnPipeline.ArtifactStoreMapProperty

    A mapping of artifactStore objects and their corresponding AWS Regions.

    CfnPipeline.ArtifactStoreProperty

    The S3 bucket where artifacts for the pipeline are stored.

    CfnPipeline.BlockerDeclarationProperty

    Reserved for future use.

    CfnPipeline.EncryptionKeyProperty

    Represents information about the key used to encrypt data in the artifact store, such as an AWS Key Management Service ( AWS KMS) key.

    CfnPipeline.InputArtifactProperty

    Represents information about an artifact to be worked on, such as a test or build artifact.

    CfnPipeline.OutputArtifactProperty

    Represents information about the output of an action.

    CfnPipeline.StageDeclarationProperty

    Represents information about a stage and its definition.

    CfnPipeline.StageTransitionProperty

    The name of the pipeline in which you want to disable the flow of artifacts from one stage to another.

    CfnPipelineProps

    Properties for defining a CfnPipeline.

    CfnWebhook

    A CloudFormation AWS::CodePipeline::Webhook.

    CfnWebhook.WebhookAuthConfigurationProperty

    The authentication applied to incoming webhook trigger requests.

    CfnWebhook.WebhookFilterRuleProperty

    The event criteria that specify when a webhook notification is sent to your URL.

    CfnWebhookProps

    Properties for defining a CfnWebhook.

    CommonActionProps

    Common properties shared by all Actions.

    CommonAwsActionProps

    Common properties shared by all Actions whose {@link ActionProperties.owner} field is 'AWS' (or unset, as 'AWS' is the default).

    CrossRegionSupport

    An interface representing resources generated in order to support the cross-region capabilities of CodePipeline.

    CustomActionProperty

    The creation attributes used for defining a configuration property of a custom Action.

    CustomActionRegistration

    The resource representing registering a custom Action with CodePipeline.

    CustomActionRegistrationProps

    Properties of registering a custom Action.

    GlobalVariables

    The CodePipeline variables that are global, not bound to a specific action.

    Pipeline

    An AWS CodePipeline pipeline with its associated IAM role and S3 bucket.

    PipelineNotificationEvents

    The list of event types for AWS Codepipeline Pipeline.

    PipelineNotifyOnOptions

    Additional options to pass to the notification rule.

    PipelineProps
    StageOptions
    StagePlacement

    Allows you to control where to place a new Stage when it's added to the Pipeline.

    StageProps

    Construction properties of a Pipeline Stage.

    Interfaces

    CfnCustomActionType.IArtifactDetailsProperty

    Returns information about the details of an artifact.

    CfnCustomActionType.IConfigurationPropertiesProperty

    The configuration properties for the custom action.

    CfnCustomActionType.ISettingsProperty

    Settings is a property of the AWS::CodePipeline::CustomActionType resource that provides URLs that users can access to view information about the CodePipeline custom action.

    CfnPipeline.IActionDeclarationProperty

    Represents information about an action declaration.

    CfnPipeline.IActionTypeIdProperty

    Represents information about an action type.

    CfnPipeline.IArtifactStoreMapProperty

    A mapping of artifactStore objects and their corresponding AWS Regions.

    CfnPipeline.IArtifactStoreProperty

    The S3 bucket where artifacts for the pipeline are stored.

    CfnPipeline.IBlockerDeclarationProperty

    Reserved for future use.

    CfnPipeline.IEncryptionKeyProperty

    Represents information about the key used to encrypt data in the artifact store, such as an AWS Key Management Service ( AWS KMS) key.

    CfnPipeline.IInputArtifactProperty

    Represents information about an artifact to be worked on, such as a test or build artifact.

    CfnPipeline.IOutputArtifactProperty

    Represents information about the output of an action.

    CfnPipeline.IStageDeclarationProperty

    Represents information about a stage and its definition.

    CfnPipeline.IStageTransitionProperty

    The name of the pipeline in which you want to disable the flow of artifacts from one stage to another.

    CfnWebhook.IWebhookAuthConfigurationProperty

    The authentication applied to incoming webhook trigger requests.

    CfnWebhook.IWebhookFilterRuleProperty

    The event criteria that specify when a webhook notification is sent to your URL.

    IAction

    A Pipeline Action.

    IActionArtifactBounds

    Specifies the constraints on the number of input and output artifacts an action can have.

    IActionBindOptions
    IActionConfig
    IActionProperties
    ICfnCustomActionTypeProps

    Properties for defining a CfnCustomActionType.

    ICfnPipelineProps

    Properties for defining a CfnPipeline.

    ICfnWebhookProps

    Properties for defining a CfnWebhook.

    ICommonActionProps

    Common properties shared by all Actions.

    ICommonAwsActionProps

    Common properties shared by all Actions whose {@link ActionProperties.owner} field is 'AWS' (or unset, as 'AWS' is the default).

    ICrossRegionSupport

    An interface representing resources generated in order to support the cross-region capabilities of CodePipeline.

    ICustomActionProperty

    The creation attributes used for defining a configuration property of a custom Action.

    ICustomActionRegistrationProps

    Properties of registering a custom Action.

    IPipeline

    The abstract view of an AWS CodePipeline as required and used by Actions.

    IPipelineNotifyOnOptions

    Additional options to pass to the notification rule.

    IPipelineProps
    IStage

    The abstract interface of a Pipeline Stage that is used by Actions.

    IStageOptions
    IStagePlacement

    Allows you to control where to place a new Stage when it's added to the Pipeline.

    IStageProps

    Construction properties of a Pipeline Stage.

    Back to top Generated by DocFX