@Stability(value=Stable)
See: Description
Interface | Description |
---|---|
ActionArtifactBounds |
Specifies the constraints on the number of input and output artifacts an action can have.
|
ActionBindOptions |
Example:
|
ActionConfig |
Example:
|
ActionProperties |
Example:
|
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.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.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
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.
|
CustomActionRegistrationProps |
Properties of registering a custom Action.
|
IAction |
A Pipeline Action.
|
IAction.Jsii$Default |
Internal default implementation for
IAction . |
IPipeline |
The abstract view of an AWS CodePipeline as required and used by Actions.
|
IPipeline.Jsii$Default |
Internal default implementation for
IPipeline . |
IStage |
The abstract interface of a Pipeline Stage that is used by Actions.
|
IStage.Jsii$Default |
Internal default implementation for
IStage . |
PipelineNotifyOnOptions |
Additional options to pass to the notification rule.
|
PipelineProps |
Example:
|
StageOptions |
Example:
|
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.
|
Enum | Description |
---|---|
ActionCategory |
Example:
|
PipelineNotificationEvents |
The list of event types for AWS Codepipeline 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();
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 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);
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 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 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
.
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());
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("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")) .build()))) .build();
See the AWS docs here for more information on cross-region CodePipelines.
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();
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.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") );
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.
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.
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);
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);
Copyright © 2023. All rights reserved.