@aws-cdk/codepipeline

AWS CodePipeline construct library

Construct an empty pipeline:

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

All of the components of a pipeline are modeled as constructs.

Append a stage to the pipeline:

const sourceStage = new Stage(pipeline, 'Source');

Add an action to a stage:

new CodeCommitSource(sourceStage, 'source', {
    artifactName: 'MyPackageSourceArtifact',
    repository: 'MyPackage'
})

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);

Reference

Action

class _aws-cdk_codepipeline.Action(parent, name, props)

Low level class for generically creating pipeline actions. It is recommended that concrete types are used instead, such as {@link CodeCommitSource} or {@link CodeBuildAction}.

Extends:

Construct

Abstract:

Yes

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (ActionProps) –
validate() → string[]

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

Return type:string
render() → @aws-cdk/resources.codepipeline.PipelineResource.ActionDeclarationProperty

Render the Action to a CloudFormation struct

Return type:ActionDeclarationProperty
onStateChange(name[, target[, options]]) → @aws-cdk/events.EventRule
Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

addChild(child, name)

If an Artifact is added as a child, add it to the list of output artifacts.

Parameters:
  • child (Construct) –
  • name (string) –
addOutputArtifact(name) → @aws-cdk/codepipeline.Artifact
Parameters:name (string) –
Return type:Artifact
addInputArtifact(artifact) → @aws-cdk/codepipeline.Action
Parameters:artifact (Artifact) –
Return type:Action
category

The category of the action. The category defines which action type the owner (the entity that performs the action) performs.

Type:ActionCategory (readonly)
provider

The service provider that the action calls.

Type:string (readonly)
configuration

The action’s configuration. These are key-value pairs that specify input values for an action. For more information, see the AWS CodePipeline User Guide. http://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements

Type:any or None (readonly)
runOrder

The order in which AWS CodePipeline runs this action. For more information, see the AWS CodePipeline User Guide. https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements

Type:number

ActionArtifactBounds (interface)

class _aws-cdk_codepipeline.ActionArtifactBounds

Specifies the constraints on the number of input and output artifacts an action can have. The constraints for each action type are documented on the {@link https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html Pipeline Structure Reference} page.

minInputs
Type:number
maxInputs
Type:number
minOutputs
Type:number
maxOutputs
Type:number

ActionCategory (enum)

class _aws-cdk_codepipeline.ActionCategory
Source
Build
Test
Approval
Deploy
Invoke

ActionProps (interface)

class _aws-cdk_codepipeline.ActionProps

Construction properties of the low level {@link Action action type}.

category

A category that defines which action type the owner (the entity that performs the action) performs. The category that you select determine the providers that you can specify for the {@link #provider} property.

Type:ActionCategory
provider

The service provider that the action calls. The providers that you can specify are determined by the category that you select. For example, a valid provider for the Deploy category is AWS CodeDeploy, which you would specify as CodeDeploy.

Type:string
artifactBounds

The constraints to apply to the number of input and output artifacts used by this action.

Type:ActionArtifactBounds
configuration

The action’s configuration. These are key-value pairs that specify input values for an action. For more information, see the AWS CodePipeline User Guide. http://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements

Type:any or None
version

For all currently supported action types, the only valid version string is “1”.

Type:string or None
owner

For all currently supported action types, the only valid owner string is “AWS”, “ThirdParty”, or “Custom”. For more information, see the AWS CodePipeline API Reference.

Type:string or None

AmazonS3Source

class _aws-cdk_codepipeline.AmazonS3Source(parent, name, props)

Source that is provided by a specific Amazon S3 object

Extends:

Source

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (AmazonS3SourceProps) –

AmazonS3SourceProps (interface)

class _aws-cdk_codepipeline.AmazonS3SourceProps

Construction properties of the {@link AmazonS3Source S3 source action}

artifactName

The name of the source’s output artifact. Output artifacts are used by CodePipeline as inputs into other actions.

Type:string
bucket

The Amazon S3 bucket that stores the source code

Type:BucketRef
bucketKey

The key within the S3 bucket that stores the source code

Type:string
pollForSourceChanges

Whether or not AWS CodePipeline should poll for source changes

Type:boolean or None

ApprovalAction

class _aws-cdk_codepipeline.ApprovalAction(parent, name)

Manual approval action

Extends:

Action

Parameters:
  • parent (Stage) –
  • name (string) –

Artifact

class _aws-cdk_codepipeline.Artifact(parent, name)

An output artifact of an action. Artifacts can be used as input by some actions.

Extends:

Construct

Parameters:
  • parent (Action) –
  • name (string) –
subartifact(fileName) → @aws-cdk/codepipeline.ArtifactPath

Returns an ArtifactPath for a file within this artifact. Output is in the form “<artifact-name>::<file-name>”

Parameters:fileName (string) – The name of the file
Return type:ArtifactPath
getParam(jsonFile, keyName) → @aws-cdk/codepipeline.ArtifactGetParam

Returns a token for a value inside a JSON file within this artifact.

Parameters:
  • jsonFile (string) – The JSON file name.
  • keyName (string) – The hash key.
Return type:

ArtifactGetParam

toString() → string

Returns a string representation of this construct.

Return type:string
name
Type:string (readonly)
bucketName

The artifact attribute for the name of the S3 bucket where the artifact is stored.

Type:ArtifactAttribute (readonly)
objectKey

The artifact attribute for The name of the .zip file that contains the artifact that is generated by AWS CodePipeline, such as 1ABCyZZ.zip.

Type:ArtifactAttribute (readonly)
url

The artifact attribute of the Amazon Simple Storage Service (Amazon S3) URL of the artifact, such as https://s3-us-west-2.amazonaws.com/artifactstorebucket-yivczw8jma0c/test/TemplateSo/1ABCyZZ.zip.

Type:ArtifactAttribute (readonly)

ArtifactAttribute

class _aws-cdk_codepipeline.ArtifactAttribute(artifact, attributeName)
Extends:

Token

Parameters:
  • artifact (Artifact) –
  • attributeName (string) –

ArtifactGetParam

class _aws-cdk_codepipeline.ArtifactGetParam(artifact, jsonFile, keyName)
Extends:

Token

Parameters:
  • artifact (Artifact) –
  • jsonFile (string) –
  • keyName (string) –

ArtifactPath

class _aws-cdk_codepipeline.ArtifactPath(artifact, fileName)

A specific file within an output artifact. The most common use case for this is specifying the template file for a CloudFormation action.

Parameters:
  • artifact (Artifact) –
  • fileName (string) –
artifact
Type:Artifact (readonly)
fileName
Type:string (readonly)
location
Type:string (readonly)

BuildAction

class _aws-cdk_codepipeline.BuildAction(parent, name, props)

Low level class for build actions. It is recommended that concrete types are used instead, such as {@link CodeBuildAction}.

Extends:

Action

Abstract:

Yes

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (BuildActionProps) –
artifact
Type:Artifact or None (readonly)

BuildActionProps (interface)

class _aws-cdk_codepipeline.BuildActionProps

Construction properties of the low level {@link BuildAction build action}

inputArtifact

The source to use as input for this build

Type:Artifact
provider

The service provider that the action calls. For example, a valid provider for Source actions is CodeBuild.

Type:string
artifactName

The name of the build’s output artifact

Type:string or None
configuration

The action’s configuration. These are key-value pairs that specify input values for an action. For more information, see the AWS CodePipeline User Guide. http://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements

Type:any or None

CodeBuildAction

class _aws-cdk_codepipeline.CodeBuildAction(parent, name, props)

Build action that uses AWS CodeBuild

Extends:

BuildAction

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (CodeBuildActionProps) –

CodeBuildActionProps (interface)

class _aws-cdk_codepipeline.CodeBuildActionProps

Construction properties of the {@link CodeBuildAction CodeBuild action}

inputArtifact

The source to use as input for this build

Type:Artifact
artifactName

The name of the build’s output artifact

Type:string or None
project

The build project

Type:BuildProjectRef

CodeCommitSource

class _aws-cdk_codepipeline.CodeCommitSource(parent, name, props)

Source that is provided by an AWS CodeCommit repository

Extends:

Source

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (CodeCommitSourceProps) –

CodeCommitSourceProps (interface)

class _aws-cdk_codepipeline.CodeCommitSourceProps

Construction properties of the {@link CodeCommitSource CodeCommit source action}

artifactName

The name of the source’s output artifact. Output artifacts are used by CodePipeline as inputs into other actions.

Type:string
repository

The CodeCommit repository.

Type:RepositoryRef
branch
Type:string or None
pollForSourceChanges

Whether or not AWS CodePipeline should poll for source changes

Type:boolean or None

GitHubSource

class _aws-cdk_codepipeline.GitHubSource(parent, name, props)

Source that is provided by a GitHub repository

Extends:

Source

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (GithubSourceProps) –

GithubSourceProps (interface)

class _aws-cdk_codepipeline.GithubSourceProps

Construction properties of the {@link GitHubSource GitHub source action}

artifactName

The name of the source’s output artifact. Output artifacts are used by CodePipeline as inputs into other actions.

Type:string
owner

The GitHub account/user that owns the repo.

Type:string
repo

The name of the repo, without the username.

Type:string
branch

The branch to use.

Type:string or None
oauthToken

A GitHub OAuth token to use for authentication. It is recommended to use a SecretParameter to obtain the token from the SSM Parameter Store: const oauth = new SecretParameter(this, ‘GitHubOAuthToken’, { ssmParameter: ‘my-github-token }); new GitHubSource(stage, ‘GH’ { oauthToken: oauth });

Type:Secret
pollForSourceChanges

Whether or not AWS CodePipeline should poll for source changes

Type:boolean or None

InvokeLambdaAction

class _aws-cdk_codepipeline.InvokeLambdaAction(parent, name, props)
Extends:

Action

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (InvokeLambdaProps) –
addInputArtifact(artifact) → @aws-cdk/codepipeline.InvokeLambdaAction

Add an input artifact

Parameters:artifact (Artifact) –
Return type:InvokeLambdaAction

InvokeLambdaProps (interface)

class _aws-cdk_codepipeline.InvokeLambdaProps
lambda

The lambda function to invoke.

Type:LambdaRef
userParameters

String to be used in the event data parameter passed to the Lambda function See an example JSON event in the CodePipeline documentation. https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-invoke-lambda-function.html#actions-invoke-lambda-function-json-event-example

Type:any or None
addPutJobResultPolicy

Adds the “codepipeline:PutJobSuccessResult” and “codepipeline:PutJobFailureResult” for ‘*’ resource to the Lambda execution role policy. NOTE: the reason we can’t add the specific pipeline ARN as a resource is to avoid a cyclic dependency between the pipeline and the Lambda function (the pipeline references) the Lambda and the Lambda needs permissions on the pipeline.

Type:boolean or None

Pipeline

class _aws-cdk_codepipeline.Pipeline(parent, name[, props])

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

Extends:

Construct

Implements:

IEventRuleTarget

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (PipelineProps or None) –
addToRolePolicy(statement)

Adds a statement to the pipeline role.

Parameters:statement (PolicyStatement) –
onStateChange(name[, target[, options]]) → @aws-cdk/events.EventRule

Defines an event rule triggered by the “CodePipeline Pipeline Execution State Change” event emitted from this pipeline.

Parameters:
  • name (string) – The name of the event rule construct. If you wish to define more than a single onStateChange event, you will need to explicitly specify a name.
  • target (IEventRuleTarget or None) – Initial target to add to the event rule. You can also add targets and customize target inputs by calling rule.addTarget(target[, * options]) after the rule was created.
  • options (EventRuleProps or None) – Additional options to pass to the event rule
Return type:

EventRule

validate() → string[]

Validate the pipeline structure Validation happens according to the rules documented at https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#pipeline-requirements

Return type:string
addChild(child, name)

If a stage is added as a child, add it to the list of stages. TODO: This is a hack that should be removed once the CDK has an onChildAdded type hook.

Parameters:
  • child (Construct) –
  • name (string) –
role

The IAM role AWS CodePipeline will use to perform actions or assume roles for actions with a more specific IAM role.

Type:Role (readonly)
pipelineArn

ARN of this pipeline

Type:PipelineArn (readonly)
artifactBucket

Bucket used to store output artifacts

Type:BucketRef (readonly)
eventRuleTarget

Allows the pipeline to be used as a CloudWatch event rule target. Usage: const pipeline = new Pipeline(this, ‘MyPipeline’); const rule = new EventRule(this, ‘MyRule’, { schedule: ‘rate(1 minute)’ }); rule.addTarget(pipeline);

Type:EventRuleTarget (readonly)

PipelineArn

class _aws-cdk_codepipeline.PipelineArn([valueOrFunction])

The ARN of a pipeline

Extends:Arn
Parameters:valueOrFunction (any or None) –

PipelineProps (interface)

class _aws-cdk_codepipeline.PipelineProps
artifactBucket

The S3 bucket used by this Pipeline to store artifacts. If not specified, a new S3 bucket will be created.

Type:BucketRef or None
restartExecutionOnUpdate

Indicates whether to rerun the AWS CodePipeline pipeline after you update it.

Type:boolean or None
pipelineName

Name of the pipeline. If you don’t specify a name, AWS CloudFormation generates an ID and uses that for the pipeline name.

Type:string or None

Source

class _aws-cdk_codepipeline.Source(parent, name, props)

Low level class for source actions. It is recommended that concrete types are used instead, such as {@link AmazonS3Source} or {@link CodeCommitSource}.

Extends:

Action

Abstract:

Yes

Parameters:
  • parent (Stage) –
  • name (string) –
  • props (SourceProps) –
artifact
Type:Artifact (readonly)

SourceProps (interface)

class _aws-cdk_codepipeline.SourceProps

Construction properties of the low level {@link Source source action}

owner

The source action owner (could e “AWS”, “ThirdParty” or “Custom”)

Type:string or None
version

The source action verison.

Type:string or None
artifactName

The name of the source’s output artifact. Output artifacts are used by CodePipeline as inputs into other actions.

Type:string
provider

The service provider that the action calls. For example, a valid provider for Source actions is S3.

Type:string
configuration

The action’s configuration. These are key-value pairs that specify input values for an action. For more information, see the AWS CodePipeline User Guide. http://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements

Type:any or None

Stage

class _aws-cdk_codepipeline.Stage(parent, name)

A stage in a pipeline. Stages are added to a pipeline by constructing a Stage with the pipeline as the first argument to the constructor.

Extends:

Construct

Parameters:
  • parent (Pipeline) –
  • name (string) –
validate() → string[]

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

Return type:string
render() → @aws-cdk/resources.codepipeline.PipelineResource.StageDeclarationProperty
Return type:StageDeclarationProperty
onStateChange(name[, target[, options]]) → @aws-cdk/events.EventRule
Parameters:
  • name (string) –
  • target (IEventRuleTarget or None) –
  • options (EventRuleProps or None) –
Return type:

EventRule

addChild(child, name)

If an action is added as a child, add it to the list of actions. TODO: This is a hack that should be removed once the CDK has an onChildAdded type hook.

Parameters:
  • child (Construct) –
  • name (string) –
pipeline

The Pipeline this stage is a member of

Type:Pipeline (readonly)
actions

Get a duplicate of this stage’s list of actions.

Type:Action (readonly)