CodePipeline pipeline structure reference
By default, any pipeline you successfully create in Amazon CodePipeline has a valid structure. However, if you manually create or edit a JSON file to create a pipeline or update a pipeline from the Amazon CLI, you might inadvertently create a structure that is not valid. The following reference can help you better understand the requirements for your pipeline structure and how to troubleshoot issues. See the constraints in Quotas in Amazon CodePipeline, which apply to all pipelines.
Topics
Valid action types and providers in CodePipeline
The pipeline structure format is used to build actions and stages in a pipeline. An action type consists of an action category and provider type.
The following are the valid action categories in CodePipeline:
-
Source
-
Build
-
Test
-
Deploy
-
Approval
-
Invoke
Each action category has a designated set of providers. Each action provider, such as
Amazon S3, has a provider name, such as S3
, that must be used in the
Provider
field in the action category in your pipeline structure.
There are three valid values for the Owner
field in the action category
section in your pipeline structure: AWS
, ThirdParty
, and
Custom
.
To find the provider name and owner information for your action provider, see Action structure reference or Number of input and output artifacts for each action type.
This table lists valid providers by action type.
Note
For Bitbucket, GitHub, or GitHub Enterprise Server actions, refer to the CodeStarSourceConnection for Bitbucket, GitHub, and GitHub Enterprise Server actions action reference topic.
Some action types in CodePipeline are available in select Amazon Regions only. It is possible that an action type is available in an Amazon Region, but an Amazon provider for that action type is not available.
For more information about each action provider, see Integrations with CodePipeline action types.
The following sections provide examples for provider information and configuration properties for each action type.
Pipeline and stage structure requirements in CodePipeline
A two-stage pipeline has the following basic structure:
{ "roleArn": "
An IAM ARN for a service role, such as arn:aws:iam::80398EXAMPLE:role/CodePipeline_Service_Role
", "stages": [ { "name": "SourceStageName
", "actions": [ ... See Action structure requirements in CodePipeline ... ] }, { "name": "NextStageName
", "actions": [ ... See Action structure requirements in CodePipeline ... ] } ], "artifactStore": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated for you the first time you create a pipeline using the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose
" }, "name": "YourPipelineName
", "version": 1 }
The pipeline structure has the following requirements:
-
A pipeline must contain at least two stages.
-
The first stage of a pipeline must contain at least one source action. It can contain source actions only.
-
Only the first stage of a pipeline can contain source actions.
-
At least one stage in each pipeline must contain an action that is not a source action.
-
All stage names in a pipeline must be unique.
-
Stage names cannot be edited in the CodePipeline console. If you edit a stage name by using the Amazon CLI, and the stage contains an action with one or more secret parameters (such as an OAuth token), the value of those secret parameters is not preserved. You must manually enter the value of the parameters (which are masked by four asterisks in the JSON returned by the Amazon CLI) and include them in the JSON structure.
-
The
artifactStore
field contains the artifact bucket type and location for a pipeline with all actions in the same Amazon Region. If you add actions in a Region different from your pipeline, theartifactStores
mapping is used to list the artifact bucket for each Amazon Region where actions are executed. When you create or edit a pipeline, you must have an artifact bucket in the pipeline Region and then you must have one artifact bucket per Region where you plan to execute an action.The following example shows the basic structure for a pipeline with cross-Region actions that uses the
artifactStores
parameter:"pipeline": { "name": "
YourPipelineName
", "roleArn": "CodePipeline_Service_Role
", "artifactStores": { "us-east-1": { "type": "S3", "location": "S3 artifact bucket name, such as codepipeline-us-east-1-1234567890
" }, "us-west-2": { "type": "S3", "location": "S3 artifact bucket name, such as codepipeline-us-west-2-1234567890
" } }, "stages": [ { ... -
The pipeline metadata fields are distinct from the pipeline structure and cannot be edited. When you update a pipeline, the date in the
updated
metadata field changes automatically. -
When you edit or update a pipeline, the pipeline name cannot be changed.
Note
If you want to rename an existing pipeline, you can use the CLI
get-pipeline
command to build a JSON file that contains your pipeline's structure. You can then use the CLIcreate-pipeline
command to create a pipeline with that structure and give it a new name.
The version number of a pipeline is automatically generated and updated every time you update the pipeline.
Action structure requirements in CodePipeline
An action has the following high-level structure:
[ { "inputArtifacts": [
An input artifact structure, if supported for the action category
], "name": "ActionName
", "region": "Region
", "namespace": "source_namespace", "actionTypeId": { "category": "An action category", "owner": "AWS", "version": "1" "provider": "A provider type for the action category
", }, "outputArtifacts": [An output artifact structure, if supported for the action category
], "configuration": {Configuration details appropriate to the provider type
}, "runOrder":A positive integer that indicates the run order within the stage
, } ]
For a list of example configuration
details appropriate to the provider
type, see Configuration details by provider
type.
The action structure has the following requirements:
-
All action names within a stage must be unique.
-
The input artifact of an action must exactly match the output artifact declared in a preceding action. For example, if a preceding action includes the following declaration:
"outputArtifacts": [ { "MyApp" } ],
and there are no other output artifacts, then the input artifact of a following action must be:
"inputArtifacts": [ { "MyApp" } ],
This is true for all actions, whether they are in the same stage or in following stages, but the input artifact does not have to be the next action in strict sequence from the action that provided the output artifact. Actions in parallel can declare different output artifact bundles, which are, in turn, consumed by different following actions.
-
Output artifact names must be unique in a pipeline. For example, a pipeline can include one action that has an output artifact named
"MyApp"
and another action that has an output artifact named"MyBuiltApp"
. However, a pipeline cannot include two actions that both have an output artifact named"MyApp"
. -
Cross-Region actions use the
Region
field to designate the Amazon Region where the actions are to be created. The Amazon resources created for this action must be created in the same Region provided in theregion
field. You cannot create cross-Region actions for the following action types:-
Source actions
-
Actions by third-party providers
-
Actions by custom providers
-
-
Actions can be configured with variables. You use the
namespace
field to set the namespace and variable information for execution variables. For reference information about execution variables and action output variables, see Variables. -
For all currently supported action types, the only valid owner string is
AWS
,ThirdParty
, orCustom
. For more information, see the CodePipeline API Reference. -
The default
runOrder
value for an action is 1. The value must be a positive integer (natural number). You cannot use fractions, decimals, negative numbers, or zero. To specify a serial sequence of actions, use the smallest number for the first action and larger numbers for each of the rest of the actions in sequence. To specify parallel actions, use the same integer for each action you want to run in parallel. In the console, you can specify a serial sequence for an action by choosing Add action group at the level in the stage where you want it to run, or you can specify a parallel sequence by choosing Add action. Action group refers to a run order of one or more actions at the same level.For example, if you want three actions to run in sequence in a stage, you would give the first action the
runOrder
value of 1, the second action therunOrder
value of 2, and the third therunOrder
value of 3. However, if you want the second and third actions to run in parallel, you would give the first action therunOrder
value of 1 and both the second and third actions therunOrder
value of 2.Note
The numbering of serial actions do not have to be in strict sequence. For example, if you have three actions in a sequence and decide to remove the second action, you do not need to renumber the
runOrder
value of the third action. Because therunOrder
value of that action (3) is higher than therunOrder
value of the first action (1), it runs serially after the first action in the stage. -
When you use an Amazon S3 bucket as a deployment location, you also specify an object key. An object key can be a file name (object) or a combination of a prefix (folder path) and file name. You can use variables to specify the location name you want the pipeline to use. Amazon S3 deployment actions support the use of the following variables in Amazon S3 object keys.
Using variables in Amazon S3Variable Example of console input Output datetime js-application/{datetime}.zip UTC timestamp in this format: <YYYY>-<MM>-DD>_<HH>-<MM>-<SS> Example:
js-application/2019-01-10_07-39-57.zip
uuid js-application/{uuid}.zip The UUID is a globally unique identifier that is guaranteed to be different from any other identifier. The UUID is in this format (all digits in hexadecimal format): <8-digits>-<4-digits>-4-digits>-<4-digits>-<12-digits> Example:
js-application/54a60075-b96a-4bf3-9013-db3a9EXAMPLE.zip
-
These are the valid
actionTypeId
categories for CodePipeline:-
Source
-
Build
-
Approval
-
Deploy
-
Test
-
Invoke
Some provider types and configuration options are provided here.
-
-
Valid provider types for an action category depend on the category. For example, for a source action type, a valid provider type is
S3
,GitHub
,CodeCommit
, orAmazon ECR
. This example shows the structure for a source action with anS3
provider:"actionTypeId": { "category": "Source", "owner": "AWS", "version": "1", "provider": "S3"},
-
Every action must have a valid action configuration, which depends on the provider type for that action. The following table lists the required action configuration elements for each valid provider type:
Action configuration properties for provider typesName of provider Provider name in action type Configuration properties Required property? Amazon S3 (Deploy action provider) For more information, including examples related to Amazon S3 deploy action parameters, see Amazon S3 deploy action. Amazon S3 (Source action provider) For more information, including examples related to Amazon S3 source action parameters, see Amazon S3 source action. Amazon ECR For more information, including examples related to Amazon ECR parameters, see Amazon ECR. CodeCommit For more information, including examples related to CodeCommit parameters, see CodeCommit. GitHub For more information, including examples related to GitHub parameters, see GitHub version 1 source action structure reference. Amazon CloudFormation For more information, including examples related to Amazon CloudFormation parameters, see Amazon CloudFormation. CodeBuild For more description and examples related to CodeBuild parameters, see Amazon CodeBuild. CodeDeploy For more description and examples related to CodeDeploy parameters, see Amazon CodeDeploy. Amazon Device Farm For more description and examples related to Amazon Device Farm parameters, see Amazon Device Farm. Amazon Elastic Beanstalk ElasticBeanstalk
ApplicationName
Required EnvironmentName
Required Amazon Lambda For more information, including examples related to Amazon Lambda parameters, see Amazon Lambda. Amazon OpsWorks Stacks OpsWorks
Stack
Required Layer
Optional App
Required Amazon ECS For more description and examples related to Amazon ECS parameters, see Amazon Elastic Container Service. Amazon ECS and CodeDeploy(Blue/Green) For more description and examples related to Amazon ECS and CodeDeploy blue/green parameters, see Amazon Elastic Container Service and CodeDeploy blue-green. Service Catalog ServiceCatalog
TemplateFilePath
Required ProductVersionName
Required ProductType
Required ProductVersionDescription
Optional ProductId
Required Alexa Skills Kit AlexaSkillsKit
ClientId
Required ClientSecret
Required RefreshToken
Required SkillId
Required Jenkins The name of the action you provided in the CodePipeline Plugin for Jenkins (for example, MyJenkinsProviderName
)ProjectName
Required Manual Approval Manual
CustomData
Optional ExternalEntityLink
Optional NotificationArn
Optional
Topics
Number of input and output artifacts for each action type
Depending on the action type, you can have the following number of input and output artifacts:
Action type constraints for artifacts | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Owner | Type of action | Provider | Valid number of input artifacts | Valid number of output artifacts | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Source | Amazon S3 | 0 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Source | CodeCommit | 0 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Source | Amazon ECR | 0 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ThirdParty |
Source | GitHub | 0 | 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Build | CodeBuild | 1 to 5 | 0 to 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Test | CodeBuild | 1 to 5 | 0 to 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Test | Amazon Device Farm | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Approval | Manual | 0 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Amazon S3 | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Amazon CloudFormation | 0 to 10 | 0 to 1 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | CodeDeploy | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Amazon Elastic Beanstalk | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Amazon OpsWorks Stacks | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Amazon ECS | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Deploy | Service Catalog | 1 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AWS |
Invoke | Amazon Lambda | 0 to 5 | 0 to 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ThirdParty |
Deploy | Alexa Skills Kit | 1 to 2 | 0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Custom |
Build | Jenkins | 0 to 5 | 0 to 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Custom |
Test | Jenkins | 0 to 5 | 0 to 5 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Custom |
Any supported category | As specified in the custom action | 0 to 5 | 0 to 5 |
Default settings for the PollForSourceChanges parameter
The PollForSourceChanges
parameter default is determined by the
method used to create the pipeline, as described in the following table. In many
cases, the PollForSourceChanges
parameter defaults to true and must be
disabled.
When the PollForSourceChanges
parameter defaults to true, you should
do the following:
-
Add the
PollForSourceChanges
parameter to the JSON file or Amazon CloudFormation template. -
Create change detection resources (CloudWatch Events rule, as applicable).
-
Set the
PollForSourceChanges
parameter to false.Note
If you create a CloudWatch Events rule or webhook, you must set the parameter to false to avoid triggering the pipeline more than once.
The
PollForSourceChanges
parameter is not used for Amazon ECR source actions.
-
PollForSourceChanges parameter defaults
Source Creation method Example "configuration" JSON structure output CodeCommit Pipeline is created with the console (and change detection resources are created by the console). The parameter is displayed in the pipeline structure output and defaults to false
.BranchName": "main", "PollForSourceChanges": "false", "RepositoryName": "my-repo"
Pipeline is created with the CLI or Amazon CloudFormation, and the PollForSourceChanges
parameter is not displayed in JSON output, but it sets totrue
.²BranchName": "main", "RepositoryName": "my-repo"
Amazon S3 Pipeline is created with the console (and change detection resources are created by the console). The parameter is displayed in the pipeline structure output and defaults to false
."S3Bucket": "my-bucket", "S3ObjectKey": "object.zip", "PollForSourceChanges": "false"
Pipeline is created with the CLI or Amazon CloudFormation, and the PollForSourceChanges
parameter is not displayed in JSON output, but it sets totrue
.²"S3Bucket": "my-bucket", "S3ObjectKey": "object.zip"
GitHub Pipeline is created with the console (and change detection resources are created by the console). The parameter is displayed in the pipeline structure output and defaults to false
."Owner": "
MyGitHubAccountName
", "Repo": "MyGitHubRepositoryName
" "PollForSourceChanges": "false", "Branch": "main
" "OAuthToken": "****
"Pipeline is created with the CLI or Amazon CloudFormation, and the PollForSourceChanges
parameter is not displayed in JSON output, but it sets totrue
.²"Owner": "
MyGitHubAccountName
", "Repo": "MyGitHubRepositoryName
", "Branch": "main
", "OAuthToken": "****
"² If
PollForSourceChanges
has been added at any point to the JSON structure or the Amazon CloudFormation template, it is displayed as shown:"PollForSourceChanges": "true",
³ For information about the change detection resources that apply to each source provider, see Change Detection Methods.
Configuration details by provider type
This section lists valid configuration
parameters for each action
provider.
The following example shows a valid configuration for a deploy action that uses Service Catalog, for a pipeline that was created in the console without a separate configuration file:
"configuration": { "TemplateFilePath": "S3_template.json", "ProductVersionName": "devops S3 v2", "ProductType": "CLOUD_FORMATION_TEMPLATE", "ProductVersionDescription": "Product version description", "ProductId": "prod-example123456" }
The following example shows a valid configuration for a deploy action that uses
Service Catalog, for a pipeline that was created in the console with a separate
sample_config.json
configuration file:
"configuration": { "ConfigurationFilePath": "sample_config.json", "ProductId": "prod-example123456" }
The following example shows a valid configuration for a deploy action that uses Alexa Skills Kit:
"configuration": { "ClientId": "amzn1.application-oa2-client.aadEXAMPLE", "ClientSecret": "****", "RefreshToken": "****", "SkillId": "amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6cEXAMPLE" }
The following example shows a valid configuration for a manual approval:
"configuration": { "CustomData": "Comments on the manual approval", "ExternalEntityLink": "http://my-url.com", "NotificationArn": "arn:aws:sns:us-west-2:12345EXAMPLE:Notification" }