aws-cdk.aws-codepipeline-actions 1.16.2

Concrete Actions for AWS Code Pipeline

AWS CodePipeline Actions

---

---

This package contains Actions that can be used in a CodePipeline.

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_codepipeline as codepipeline
import aws_cdk.aws_codepipeline_actions as codepipeline_actions

Sources

AWS CodeCommit

To use a CodeCommit Repository in a CodePipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_codecommit as codecommit

repo = codecommit.Repository(self, "Repo")

pipeline = codepipeline.Pipeline(self, "MyPipeline",
    pipeline_name="MyPipeline"
)
source_output = codepipeline.Artifact()
source_action = codepipeline_actions.CodeCommitSourceAction(
    action_name="CodeCommit",
    repository=repo,
    output=source_output
)
pipeline.add_stage(
    stage_name="Source",
    actions=[source_action]
)

GitHub

To use GitHub as the source of a CodePipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
# Read the secret from Secrets Manager
source_output = codepipeline.Artifact()
source_action = codepipeline_actions.GitHubSourceAction(
    action_name="GitHub_Source",
    owner="awslabs",
    repo="aws-cdk",
    oauth_token=cdk.SecretValue.secrets_manager("my-github-token"),
    output=source_output,
    branch="develop", # default: 'master'
    trigger=codepipeline_actions.GitHubTrigger.POLL
)
pipeline.add_stage(
    stage_name="Source",
    actions=[source_action]
)

AWS S3

To use an S3 Bucket as a source in CodePipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_s3 as s3

source_bucket = s3.Bucket(self, "MyBucket",
    versioned=True
)

pipeline = codepipeline.Pipeline(self, "MyPipeline")
source_output = codepipeline.Artifact()
source_action = codepipeline_actions.S3SourceAction(
    action_name="S3Source",
    bucket=source_bucket,
    bucket_key="path/to/file.zip",
    output=source_output
)
pipeline.add_stage(
    stage_name="Source",
    actions=[source_action]
)

By default, the Pipeline will poll the Bucket to detect changes. You can change that behavior to use CloudWatch Events by setting the trigger property to S3Trigger.EVENTS (it's S3Trigger.POLL by default). If you do that, make sure the source Bucket is part of an AWS CloudTrail Trail - otherwise, the CloudWatch Events will not be emitted, and your Pipeline will not react to changes in the Bucket. You can do it through the CDK:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_cloudtrail as cloudtrail

key = "some/key.zip"
trail = cloudtrail.Trail(self, "CloudTrail")
trail.add_s3_event_selector([source_bucket.arn_for_objects(key)],
    read_write_type=cloudtrail.ReadWriteType.WRITE_ONLY
)
source_action = codepipeline_actions.S3SourceAction(
    action_name="S3Source",
    bucket_key=key,
    bucket=source_bucket,
    output=source_output,
    trigger=codepipeline_actions.S3Trigger.EVENTS
)

AWS ECR

To use an ECR Repository as a source in a Pipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_ecr as ecr

pipeline = codepipeline.Pipeline(self, "MyPipeline")
source_output = codepipeline.Artifact()
source_action = codepipeline_actions.EcrSourceAction(
    action_name="ECR",
    repository=ecr_repository,
    image_tag="some-tag", # optional, default: 'latest'
    output=source_output
)
pipeline.add_stage(
    stage_name="Source",
    actions=[source_action]
)

Build & test

AWS CodeBuild

Example of a CodeBuild Project used in a Pipeline, alongside CodeCommit:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_codebuild as codebuild
import aws_cdk.aws_codecommit as codecommit

repository = codecommit.Repository(self, "MyRepository",
    repository_name="MyRepository"
)
project = codebuild.PipelineProject(self, "MyProject")

source_output = codepipeline.Artifact()
source_action = codepipeline_actions.CodeCommitSourceAction(
    action_name="CodeCommit",
    repository=repository,
    output=source_output
)
build_action = codepipeline_actions.CodeBuildAction(
    action_name="CodeBuild",
    project=project,
    input=source_output,
    outputs=[codepipeline.Artifact()]
)

codepipeline.Pipeline(self, "MyPipeline",
    stages=[{
        "stage_name": "Source",
        "actions": [source_action]
    }, {
        "stage_name": "Build",
        "actions": [build_action]
    }
    ]
)

The default category of the CodeBuild Action is Build; if you want a Test Action instead, override the type property:

# Example may have issues. See https://github.com/aws/jsii/issues/826
test_action = codepipeline_actions.CodeBuildAction(
    action_name="IntegrationTest",
    project=project,
    input=source_output,
    type=codepipeline_actions.CodeBuildActionType.TEST
)

Multiple inputs and outputs

When you want to have multiple inputs and/or outputs for a Project used in a Pipeline, instead of using the secondarySources and secondaryArtifacts properties of the Project class, you need to use the extraInputs and extraOutputs properties of the CodeBuild CodePipeline Actions. Example:

# Example may have issues. See https://github.com/aws/jsii/issues/826
source_output1 = codepipeline.Artifact()
source_action1 = codepipeline_actions.CodeCommitSourceAction(
    action_name="Source1",
    repository=repository1,
    output=source_output1
)
source_output2 = codepipeline.Artifact("source2")
source_action2 = codepipeline_actions.CodeCommitSourceAction(
    action_name="Source2",
    repository=repository2,
    output=source_output2
)

build_action = codepipeline_actions.CodeBuildAction(
    action_name="Build",
    project=project,
    input=source_output1,
    extra_inputs=[source_output2
    ],
    outputs=[
        codepipeline.Artifact("artifact1"), # for better buildspec readability - see below
        codepipeline.Artifact("artifact2")
    ]
)

Note: when a CodeBuild Action in a Pipeline has more than one output, it only uses the secondary-artifacts field of the buildspec, never the primary output specification directly under artifacts. Because of that, it pays to explicitly name all output artifacts of that Action, like we did above, so that you know what name to use in the buildspec.

Example buildspec for the above project:

# Example may have issues. See https://github.com/aws/jsii/issues/826
project = codebuild.PipelineProject(self, "MyProject",
    build_spec=codebuild.BuildSpec.from_object(
        version="0.2",
        phases={
            "build": {
                "commands": []
            }
        },
        artifacts={
            "secondary-artifacts": {
                "artifact1": {},
                "artifact2": {}
            }
        }
    )
)

Jenkins

In order to use Jenkins Actions in the Pipeline, you first need to create a JenkinsProvider:

# Example may have issues. See https://github.com/aws/jsii/issues/826
jenkins_provider = codepipeline_actions.JenkinsProvider(self, "JenkinsProvider",
    provider_name="MyJenkinsProvider",
    server_url="http://my-jenkins.com:8080",
    version="2"
)

If you've registered a Jenkins provider in a different CDK app, or outside the CDK (in the CodePipeline AWS Console, for example), you can import it:

# Example may have issues. See https://github.com/aws/jsii/issues/826
jenkins_provider = codepipeline_actions.JenkinsProvider.import(self, "JenkinsProvider",
    provider_name="MyJenkinsProvider",
    server_url="http://my-jenkins.com:8080",
    version="2"
)

Note that a Jenkins provider (identified by the provider name-category(build/test)-version tuple) must always be registered in the given account, in the given AWS region, before it can be used in CodePipeline.

With a JenkinsProvider, we can create a Jenkins Action:

# Example may have issues. See https://github.com/aws/jsii/issues/826
build_action = codepipeline_actions.JenkinsAction(
    action_name="JenkinsBuild",
    jenkins_provider=jenkins_provider,
    project_name="MyProject",
    type=ccodepipeline_actions.JenkinsActionType.BUILD
)

Deploy

AWS CloudFormation

This module contains Actions that allows you to deploy to CloudFormation from AWS CodePipeline.

For example, the following code fragment defines a pipeline that automatically deploys a CloudFormation template directly from a CodeCommit repository, with a manual approval step in between to confirm the changes:

# Example may have issues. See https://github.com/aws/jsii/issues/826
# Source stage: read from repository
repo = codecommit.Repository(stack, "TemplateRepo",
    repository_name="template-repo"
)
source_output = codepipeline.Artifact("SourceArtifact")
source = cpactions.CodeCommitSourceAction(
    action_name="Source",
    repository=repo,
    output=source_output,
    trigger=cpactions.CodeCommitTrigger.POLL
)
source_stage = {
    "stage_name": "Source",
    "actions": [source]
}

# Deployment stage: create and deploy changeset with manual approval
stack_name = "OurStack"
change_set_name = "StagedChangeSet"

prod_stage = {
    "stage_name": "Deploy",
    "actions": [
        cpactions.CloudFormationCreateReplaceChangeSetAction(
            action_name="PrepareChanges",
            stack_name=stack_name,
            change_set_name=change_set_name,
            admin_permissions=True,
            template_path=source_output.at_path("template.yaml"),
            run_order=1
        ),
        cpactions.ManualApprovalAction(
            action_name="ApproveChanges",
            run_order=2
        ),
        cpactions.CloudFormationExecuteChangeSetAction(
            action_name="ExecuteChanges",
            stack_name=stack_name,
            change_set_name=change_set_name,
            run_order=3
        )
    ]
}

codepipeline.Pipeline(stack, "Pipeline",
    stages=[source_stage, prod_stage
    ]
)

See the AWS documentation for more details about using CloudFormation in CodePipeline.

Actions defined by this package

This package defines the following actions:

• CloudFormationCreateUpdateStackAction - Deploy a CloudFormation template directly from the pipeline. The indicated stack is created, or updated if it already exists. If the stack is in a failure state, deployment will fail (unless replaceOnFailure is set to true, in which case it will be destroyed and recreated).
• CloudFormationDeleteStackAction - Delete the stack with the given name.
• CloudFormationCreateReplaceChangeSetAction - Prepare a change set to be applied later. You will typically use change sets if you want to manually verify the changes that are being staged, or if you want to separate the people (or system) preparing the changes from the people (or system) applying the changes.
• CloudFormationExecuteChangeSetAction - Execute a change set prepared previously.

Lambda deployed through CodePipeline

If you want to deploy your Lambda through CodePipeline, and you don't use assets (for example, because your CDK code and Lambda code are separate), you can use a special Lambda Code class, CfnParametersCode. Note that your Lambda must be in a different Stack than your Pipeline. The Lambda itself will be deployed, alongside the entire Stack it belongs to, using a CloudFormation CodePipeline Action. Example:

# Example may have issues. See https://github.com/aws/jsii/issues/826
lambda_stack = cdk.Stack(app, "LambdaStack")
lambda_code = lambda.Code.from_cfn_parameters()
lambda.Function(lambda_stack, "Lambda",
    code=lambda_code,
    handler="index.handler",
    runtime=lambda.Runtime.NODEJS_8_10
)
# other resources that your Lambda needs, added to the lambdaStack...

pipeline_stack = cdk.Stack(app, "PipelineStack")
pipeline = codepipeline.Pipeline(pipeline_stack, "Pipeline")

# add the source code repository containing this code to your Pipeline,
# and the source code of the Lambda Function, if they're separate
cdk_source_output = codepipeline.Artifact()
cdk_source_action = codepipeline_actions.CodeCommitSourceAction(
    repository=codecommit.Repository(pipeline_stack, "CdkCodeRepo",
        repository_name="CdkCodeRepo"
    ),
    action_name="CdkCode_Source",
    output=cdk_source_output
)
lambda_source_output = codepipeline.Artifact()
lambda_source_action = codepipeline_actions.CodeCommitSourceAction(
    repository=codecommit.Repository(pipeline_stack, "LambdaCodeRepo",
        repository_name="LambdaCodeRepo"
    ),
    action_name="LambdaCode_Source",
    output=lambda_source_output
)
pipeline.add_stage(
    stage_name="Source",
    actions=[cdk_source_action, lambda_source_action]
)

# synthesize the Lambda CDK template, using CodeBuild
# the below values are just examples, assuming your CDK code is in TypeScript/JavaScript -
# adjust the build environment and/or commands accordingly
cdk_build_project = codebuild.Project(pipeline_stack, "CdkBuildProject",
    environment={
        "build_image": codebuild.LinuxBuildImage.UBUNTU_14_04_NODEJS_10_1_0
    },
    build_spec=codebuild.BuildSpec.from_object(
        version="0.2",
        phases={
            "install": {
                "commands": "npm install"
            },
            "build": {
                "commands": ["npm run build", "npm run cdk synth LambdaStack -- -o ."
                ]
            }
        },
        artifacts={
            "files": "LambdaStack.template.yaml"
        }
    )
)
cdk_build_output = codepipeline.Artifact()
cdk_build_action = codepipeline_actions.CodeBuildAction(
    action_name="CDK_Build",
    project=cdk_build_project,
    input=cdk_source_output,
    outputs=[cdk_build_output]
)

# build your Lambda code, using CodeBuild
# again, this example assumes your Lambda is written in TypeScript/JavaScript -
# make sure to adjust the build environment and/or commands if they don't match your specific situation
lambda_build_project = codebuild.Project(pipeline_stack, "LambdaBuildProject",
    environment={
        "build_image": codebuild.LinuxBuildImage.UBUNTU_14_04_NODEJS_10_1_0
    },
    build_spec=codebuild.BuildSpec.from_object(
        version="0.2",
        phases={
            "install": {
                "commands": "npm install"
            },
            "build": {
                "commands": "npm run build"
            }
        },
        artifacts={
            "files": ["index.js", "node_modules/**/*"
            ]
        }
    )
)
lambda_build_output = codepipeline.Artifact()
lambda_build_action = codepipeline_actions.CodeBuildAction(
    action_name="Lambda_Build",
    project=lambda_build_project,
    input=lambda_source_output,
    outputs=[lambda_build_output]
)

pipeline.add_stage(
    stage_name="Build",
    actions=[cdk_build_action, lambda_build_action]
)

# finally, deploy your Lambda Stack
pipeline.add_stage(
    stage_name="Deploy",
    actions=[
        codepipeline_actions.CloudFormationCreateUpdateStackAction(
            action_name="Lambda_CFN_Deploy",
            template_path=cdk_build_output.at_path("LambdaStack.template.yaml"),
            stack_name="LambdaStackDeployedName",
            admin_permissions=True,
            parameter_overrides={
                (SpreadAssignment ...lambdaCode.assign(lambdaBuildOutput.s3Location)
                  lambda_code.assign(lambda_build_output.s3_location))
            },
            extra_inputs=[lambda_build_output
            ]
        )
    ]
)

Cross-account actions

If you want to update stacks in a different account, pass the account property when creating the action:

# Example may have issues. See https://github.com/aws/jsii/issues/826
codepipeline_actions.CloudFormationCreateUpdateStackAction(
    # ...
    account="123456789012"
)

This will create a new stack, called <PipelineStackName>-support-123456789012, in your App, that will contain the role that the pipeline will assume in account 123456789012 before executing this action. This support stack will automatically be deployed before the stack containing the pipeline.

You can also pass a role explicitly when creating the action - in that case, the account property is ignored, and the action will operate in the same account the role belongs to:

# Example may have issues. See https://github.com/aws/jsii/issues/826
from aws_cdk.core import PhysicalName

# in stack for account 123456789012...
action_role = iam.Role(other_account_stack, "ActionRole",
    assumed_by=iam.AccountPrincipal(pipeline_account),
    # the role has to have a physical name set
    role_name=PhysicalName.GENERATE_IF_NEEDED
)

# in the pipeline stack...
codepipeline_actions.CloudFormationCreateUpdateStackAction(
    # ...
    role=action_role
)

AWS CodeDeploy

Server deployments

To use CodeDeploy for EC2/on-premise deployments in a Pipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_codedeploy as codedeploy

pipeline = codepipeline.Pipeline(self, "MyPipeline",
    pipeline_name="MyPipeline"
)

# add the source and build Stages to the Pipeline...

deploy_action = codepipeline_actions.CodeDeployServerDeployAction(
    action_name="CodeDeploy",
    input=build_output,
    deployment_group=deployment_group
)
pipeline.add_stage(
    stage_name="Deploy",
    actions=[deploy_action]
)

Lambda deployments

To use CodeDeploy for blue-green Lambda deployments in a Pipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
lambda_code = lambda.Code.from_cfn_parameters()
func = lambda.Function(lambda_stack, "Lambda",
    code=lambda_code,
    handler="index.handler",
    runtime=lambda.Runtime.NODEJS_8_10
)
# used to make sure each CDK synthesis produces a different Version
version = func.add_version("NewVersion")
alias = lambda.Alias(lambda_stack, "LambdaAlias",
    alias_name="Prod",
    version=version
)

codedeploy.LambdaDeploymentGroup(lambda_stack, "DeploymentGroup",
    alias=alias,
    deployment_config=codedeploy.LambdaDeploymentConfig.LINEAR_10PERCENT_EVERY_1MINUTE
)

Then, you need to create your Pipeline Stack, where you will define your Pipeline, and deploy the lambdaStack using a CloudFormation CodePipeline Action (see above for a complete example).

ECS

CodePipeline can deploy an ECS service. The deploy Action receives one input Artifact which contains the image definition file:

# Example may have issues. See https://github.com/aws/jsii/issues/826
deploy_stage = pipeline.add_stage(
    stage_name="Deploy",
    actions=[
        codepipeline_actions.EcsDeployAction(
            action_name="DeployAction",
            service=service,
            # if your file is called imagedefinitions.json,
            # use the `input` property,
            # and leave out the `imageFile` property
            input=build_output,
            # if your file name is _not_ imagedefinitions.json,
            # use the `imageFile` property,
            # and leave out the `input` property
            image_file=build_output.at_path("imageDef.json")
        )
    ]
)

AWS S3

To use an S3 Bucket as a deployment target in CodePipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
target_bucket = s3.Bucket(self, "MyBucket")

pipeline = codepipeline.Pipeline(self, "MyPipeline")
deploy_action = codepipeline_actions.S3DeployAction(
    action_name="S3Deploy",
    stage=deploy_stage,
    bucket=target_bucket,
    input=source_output
)
deploy_stage = pipeline.add_stage(
    stage_name="Deploy",
    actions=[deploy_action]
)

Alexa Skill

You can deploy to Alexa using CodePipeline with the following Action:

# Example may have issues. See https://github.com/aws/jsii/issues/826
# Read the secrets from ParameterStore
client_id = cdk.SecretValue.secrets_manager("AlexaClientId")
client_secret = cdk.SecretValue.secrets_manager("AlexaClientSecret")
refresh_token = cdk.SecretValue.secrets_manager("AlexaRefreshToken")

# Add deploy action
codepipeline_actions.AlexaSkillDeployAction(
    action_name="DeploySkill",
    run_order=1,
    input=source_output,
    client_id=client_id.to_string(),
    client_secret=client_secret,
    refresh_token=refresh_token,
    skill_id="amzn1.ask.skill.12345678-1234-1234-1234-123456789012"
)

If you need manifest overrides you can specify them as parameterOverridesArtifact in the action:

# Example may have issues. See https://github.com/aws/jsii/issues/826
cloudformation = require("@aws-cdk/aws-cloudformation")

# Deploy some CFN change set and store output
execute_output = codepipeline.Artifact("CloudFormation")
execute_change_set_action = codepipeline_actions.CloudFormationExecuteChangeSetAction(
    action_name="ExecuteChangesTest",
    run_order=2,
    stack_name=stack_name,
    change_set_name=change_set_name,
    output_file_name="overrides.json",
    output=execute_output
)

# Provide CFN output as manifest overrides
codepipeline_actions.AlexaSkillDeployAction(
    action_name="DeploySkill",
    run_order=1,
    input=source_output,
    parameter_overrides_artifact=execute_output,
    client_id=client_id.to_string(),
    client_secret=client_secret,
    refresh_token=refresh_token,
    skill_id="amzn1.ask.skill.12345678-1234-1234-1234-123456789012"
)

Approve & invoke

Manual approval Action

This package contains an Action that stops the Pipeline until someone manually clicks the approve button:

# Example may have issues. See https://github.com/aws/jsii/issues/826
manual_approval_action = codepipeline_actions.ManualApprovalAction(
    action_name="Approve",
    notification_topic=sns.Topic(self, "Topic"), # optional
    notify_emails=["[e-mail]"
    ], # optional
    additional_information="additional info"
)
approve_stage.add_action(manual_approval_action)

If the notificationTopic has not been provided, but notifyEmails were, a new SNS Topic will be created (and accessible through the notificationTopic property of the Action).

AWS Lambda

This module contains an Action that allows you to invoke a Lambda function in a Pipeline:

# Example may have issues. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_lambda as lambda

pipeline = codepipeline.Pipeline(self, "MyPipeline")
lambda_action = codepipeline_actions.LambdaInvokeAction(
    action_name="Lambda",
    lambda=fn
)
pipeline.add_stage(
    stage_name="Lambda",
    actions=[lambda_action]
)

The Lambda Action can have up to 5 inputs, and up to 5 outputs:

# Example may have issues. See https://github.com/aws/jsii/issues/826

lambda_action = codepipeline_actions.LambdaInvokeAction(
    action_name="Lambda",
    inputs=[source_output, build_output
    ],
    outputs=[
        codepipeline.Artifact("Out1"),
        codepipeline.Artifact("Out2")
    ],
    lambda=fn
)

See the AWS documentation on how to write a Lambda function invoked from CodePipeline.