CodePipeline
User Guide (API Version 2015-07-09)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

CodePipeline Pipeline Structure Reference

By default, any pipeline you successfully create in AWS 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 AWS 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 Limits in AWS CodePipeline, which apply to all pipelines.

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. This table lists valid providers by action type.

Valid Action Providers by Action Type

Action Category Valid Action Providers
Source Amazon S3
CodeCommit
GitHub
Amazon ECR
Build CodeBuild
Custom CloudBees
Custom Jenkins
Custom TeamCity
Test CodeBuild
AWS Device Farm
Custom BlazeMeter
ThirdParty GhostInspector
Custom Jenkins
ThirdParty Micro Focus StormRunner Load
ThirdParty Nouvola
ThirdParty Runscope
Deploy Amazon S3
AWS CloudFormation
CodeDeploy
Amazon ECS
Elastic Beanstalk
AWS OpsWorks
AWS Service Catalog
Amazon Alexa
Custom XebiaLabs
Approval Manual
Invoke AWS Lambda

Some action types in CodePipeline are available in select AWS Regions only. It is possible that an action type is available in an AWS Region, but an AWS 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/AWS-CodePipeline-Service", "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 AWS 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 type the value of the parameters (which are masked by four asterisks in the JSON returned by the AWS 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 AWS Region. If you add actions in a Region different from your pipeline, the artifactStores mapping is used to list the artifact bucket for each AWS 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": "ServiceRoleARN", "artifactStores": { "us-east-1": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated as the default when you use the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" }, "us-west-2": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated as the default when you use the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" } }, "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 CLI create-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", "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.

    The following illustration provides an example of input and output artifacts in actions in a pipeline:

    
                        An example of input and output artifacts in actions in a
                            pipeline.
  • 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 AWS Region where the actions is to be created. The AWS resources created for this action must be created in the same Region provided in the Region field. You cannot create cross-region actions for the following actions types:

    • Source actions

    • Actions by third-party providers

    • Actions by custom providers

  • If an action contains a parameter whose value is secret, such as the OAuth token for a GitHub source action, the value of that parameter is masked in the JSON by a series of four asterisks (****). The actual value is stored, and as long as you do not edit that value, or change the name of the action or the name of the stage where that action runs, you do not have to supply that value when editing the JSON using the AWS CLI or CodePipeline API. However, if you change the name of the action, or the name of the stage in which the action runs, the value of any secret parameters is lost. You must manually type the values for any secret parameters in the JSON, or the action fails the next time the pipeline runs.

  • For all currently supported action types, the only valid version string is "1".

  • For all currently supported action types, the only valid owner string is "AWS", "ThirdParty", or "Custom". 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.

    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 the runOrder value of 2, and the third the runOrder value of 3. However, if you want the second and third actions to run in parallel, you would give the first action the runOrder value of 1 and both the second and third actions the runOrder 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 the runOrder value of that action (3) is higher than the runOrder 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 S3

    Variable 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

  • 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 AWS Device Farm 1 0
    AWS Approval Manual 0 0
    AWS Deploy Amazon S3 1 0
    AWS Deploy AWS CloudFormation 0 to 10 0 to 1
    AWS Deploy CodeDeploy 1 0
    AWS Deploy AWS Elastic Beanstalk 1 0
    AWS Deploy AWS OpsWorks Stacks 1 0
    AWS Deploy Amazon ECS 1 0
    AWS Deploy AWS Service Catalog 1 0
    AWS Invoke AWS 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
  • 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, or Amazon ECR. This example shows the structure for a source action with an S3 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 Types

    Name of Provider Provider Name in Action Type Configuration Properties Required Property?
    Amazon S3 (Source action provider) S3 S3Bucket Required
    PollForSourceChanges¹ Optional
    S3ObjectKey Required
    Amazon S3 (Deploy action provider) S3 BucketName Required
    Extract Required
    ObjectKey Required if Extract = false
    KMSEncryptionKeyARN² Optional
    CannedACL³ Optional
    CacheControl4 Optional
    CodeCommit CodeCommit PollForSourceChanges¹ Optional
    RepositoryName Required
    BranchName Required
    GitHub GitHub Owner Required
    Repo Required
    PollForSourceChanges¹ Optional
    Branch Required
    OAuthToken Required
    Amazon ECR ECR ImageTag Optional
    RepositoryName Required
    AWS CloudFormation For more information, including examples related to AWS CloudFormation parameters, see CloudFormation.
    CodeBuild For more description and examples related to CodeBuild parameters, see CodeBuild.
    CodeDeploy CodeDeploy ApplicationName Required
    DeploymentGroupName Required
    AWS Device Farm DeviceFarm RecordAppPerformanceData Required
    AppType Required
    ProjectId Required
    App Required
    RadioBluetoothEnabled Default=true
    RecordVideo Default=true
    RadioWifiEnabled Default=true
    RadioNfcEnabled Default=true
    RadioGpsEnabled Default=true
    Test Required
    DevicePoolArn Required
    TestType Required
    AppiumVersion Required
    AWS Elastic Beanstalk ElasticBeanstalk ApplicationName Required
    EnvironmentName Required
    AWS Lambda For more information, including examples related to AWS Lambda parameters, see Lambda.
    AWS OpsWorks Stacks OpsWorks Stack Required
    Layer Optional
    App Required
    Amazon ECS ECS ClusterName Required
    ServiceName Required
    FileName Optional
    Amazon ECS (Blue/Green) CodeDeployToECS5 ApplicationName Required
    DeploymentGroupName Required
    TaskDefinitionTemplateArtifact Required
    AppSpecTemplateArtifact Required
    AppSpecTemplatePath Required
    TaskDefinitionTemplatePath Optional
    Image1ArtifactName Optional
    Image1ContainerName Optional
    Image2ArtifactName Optional
    Image2ContainerName Optional
    Image3ArtifactName Optional
    Image3ContainerName Optional
    Image4ArtifactName Optional
    Image4ContainerName Optional
    AWS 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

    ¹In many cases, the PollForSourceChanges parameter defaults to true when you create a pipeline. When you add event-based change detection, you must add the parameter to your output and set it to false to disable polling. Otherwise, your pipeline starts twice for a single source change. For more information, see Default Settings for the PollForSourceChanges Parameter.

    For pipelines or source actions created or updated in the console after the following dates, the PollForSourceChanges parameter defaults to false:

    • CodeCommit pipelines created or updated in the console after October 11, 2017.

    • Amazon S3 pipelines created or updated in the console after March 22, 2018.

    • GitHub pipelines created or updated in the console after May 1, 2018.

    ²The KMSEncryptionKeyARN parameter encrypts uploaded artifacts with the provided KMS key. For an AWS KMS key, you can use the key ID, the key ARN, or the alias ARN.

    Note

    Aliases are recognized only in the account that created the customer master key (CMK). For cross-account actions, you can only use the key ID or key ARN to identify the key.

    ³The CannedACL parameter applies the specified canned ACL to objects deployed to Amazon S3. This overwrites any existing ACL that was applied to the object.

    4The CacheControl parameter controls caching behavior for requests/responses for objects in the bucket. For a list of valid values, see the Cache-Control header field for HTTP operations. To enter multiple values in CacheControl, use a comma between each value. You can add a space after each comma (optional), as shown in this example for the CLI:

    "CacheControl": "public, max-age=0, no-transform"

    5For a tutorial that demonstrates creating a pipeline with several of these parameters, including Image1ContainerName, see Step 6: Create Your Pipeline .

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 AWS CloudFormation template.

  • Create change detection resources (CloudWatch Events rule or webhook, 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 trigering 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": "master", "PollForSourceChanges": "false", "RepositoryName": "my-repo"
    Pipeline is created with the CLI or AWS CloudFormation, and the PollForSourceChanges parameter is not displayed in JSON output, but it sets to true
    BranchName": "master", "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 AWS CloudFormation, and the PollForSourceChanges parameter lparameter line is not displayed in JSON output, but it sets to true
    "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": "master" "OAuthToken": "****"
    Pipeline is created with the CLI or AWS CloudFormation, and the PollForSourceChanges parameter is not displayed in JSON output, but it sets to true
    "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "Branch": "master", "OAuthToken": "****"

    ² If PollForSourceChanges has been added at any point to the JSON structure or the AWS 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 action configuration for a source action that uses Amazon S3:

"configuration": { "S3Bucket": "awscodepipeline-demobucket-example-date", "S3ObjectKey": "CodePipelineDemoApplication.zip", "PollForSourceChanges": "false" }

The following example shows the action configuration returned for a source action that uses GitHub:

"configuration": { "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "PollForSourceChanges": "false", "Branch": "master", "OAuthToken": "****" },

The following example shows the action configuration returned for a source action that uses Amazon ECR:

"configuration": { "ImageTag": "latest", "RepositoryName": "my-image-repo" },

The following example shows a valid configuration for a deploy action that uses Amazon ECS:

"configuration": { "ClusterName": "my-ecs-cluster", "ServiceName": "sample-app-service", "FileName": "imagedefinitions.json", }

The following example shows a valid configuration for a test action that uses AWS Device Farm:

"configuration": { "RecordAppPerformanceData": "true", "AppType": "Android", "ProjectId": "Project_ID", "App": "app-release.apk", "RadioBluetoothEnabled": "true", "RecordVideo": "true", "RadioWifiEnabled": "true", "RadioNfcEnabled": "true", "RadioGpsEnabled": "true", "Test": "tests.zip", "DevicePoolArn": "ARN", "TestType": "Calabash", "AppiumVersion": "1.7.2" }

The following example shows a valid configuration for a deploy action that uses AWS 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 AWS 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 deploy action that uses Amazon S3:

"configuration": { "BucketName": "website-bucket", "Extract": "true", "ObjectKey": "MyWebsite" }

The following example shows a valid configuration for an Amazon ECS and CodeDeploy blue/green deployment:

"configuration": { "ApplicationName": "codedeploy-ecs-application", "DeploymentGroupName": "ecs-codedeploy-deplgroup", "Image1ArtifactName": "MyImage", "TaskDefinitionTemplateArtifact": "SourceArtifact", "Image1ContainerName": "IMAGE1_NAME", "TaskDefinitionTemplatePath": "taskdef.json", "AppSpecTemplateArtifact": "SourceArtifact", "AppSpecTemplatePath": "appspec.yaml", }

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" }