Pipeline

List of all available properties for a Copilot pipeline manifest. To learn more about pipelines, see the Pipelines concept page.

Sample continuous delivery pipeline manifests

Release workloadsControl order of deploymentsRelease environments

# The "app-pipeline" will deploy all the services and jobs in the user/repo
# to the "test" and "prod" environments.
name: app-pipeline

source:
  provider: GitHub
  properties:
    branch: main
    repository: https://github.com/user/repo
    # Optional: specify the name of an existing CodeStar Connections connection.
    # connection_name: a-connection

build:
  image: aws/codebuild/amazonlinux2-x86_64-standard:5.0
  # additional_policy: # Add additional permissions while building your container images and templates.

stages: 
  - # By default all workloads are deployed concurrently within a stage.
    name: test
    pre_deployments:
      db_migration:
        buildspec: ./buildspec.yml
    test_commands:
      - make integ-test
      - echo "woo! Tests passed"
  -
    name: prod
    requires_approval: true

# Alternatively, you can control the order of stack deployments in a stage. 
# See https://aws.github.io/copilot-cli/blogs/release-v118/#controlling-order-of-deployments-in-a-pipeline
name: app-pipeline

source:
  provider: Bitbucket
  properties:
    branch: main
    repository:  https://bitbucket.org/user/repo

stages:
  - name: test
    deployments:
      orders:
      warehouse:
      frontend:
        depends_on: [orders, warehouse]
  - name: prod
    require_approval: true
    deployments:
      orders:
      warehouse:
      frontend:
        depends_on: [orders, warehouse]

# Environment manifests changes can also be released with a pipeline.
name: env-pipeline

source:
  provider: CodeCommit
  properties:
    branch: main
    repository: https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo

stages:
  - name: test
    deployments:
      deploy-env:
        template_path: infrastructure/test.env.yml
        template_config: infrastructure/test.env.params.json
        stack_name: app-test
  - name: prod
    deployments:
      deploy-prod:
        template_path: infrastructure/prod.env.yml
        template_config: infrastructure/prod.env.params.json
        stack_name: app-prod

name String
The name of your pipeline.

version String
The schema version for the template. There is only one version, 1, supported at the moment.

source Map
Configuration for how your pipeline is triggered.

source.provider String
The name of your provider. Currently, GitHub, Bitbucket, and CodeCommit are supported.

source.properties Map
Provider-specific configuration on how the pipeline is triggered.

source.properties.access_token_secret String
The name of AWS Secrets Manager secret that holds the GitHub access token to trigger the pipeline if your provider is GitHub and you created your pipeline with a personal access token.

Info

As of AWS Copilot v1.4.0, the access token is no longer needed for GitHub repository sources. Instead, Copilot will trigger the pipeline using AWS CodeStar connections.

source.properties.branch String
The name of the branch in your repository that triggers the pipeline. Copilot autofills this field with your current local branch.

source.properties.repository String
The URL of your repository.

source.properties.connection_name String
The name of an existing CodeStar Connections connection. If omitted, Copilot will generate a connection for you.

source.properties.output_artifact_format String
Optional. The output artifact format. Values can be either CODEBUILD_CLONE_REF or CODE_ZIP. If omitted, the default is CODE_ZIP.

Info

This property is not available for pipelines with GitHub version 1 source actions, which use access_token_secret.

build Map
Configuration for CodeBuild project.

build.image String
The URI that identifies the Docker image to use for this build project. As of now, aws/codebuild/amazonlinux2-x86_64-standard:5.0 is used by default.

build.buildspec String
Optional. The path to a buildspec file, relative to the project root, to use for this build project. By default, Copilot will generate one for you, located at copilot/pipelines/[your pipeline name]/buildspec.yml.

build.additional_policy.PolicyDocument Map
Optional. Specify an additional policy document to add to the build project role. The additional policy document can be specified in a map in YAML, for example:

build:
  additional_policy:
    PolicyDocument:
      Version: '2012-10-17'
      Statement:
        - Effect: Allow
          Action:
            - ecr:GetAuthorizationToken
          Resource: '*'

or alternatively as JSON:

build:
  additional_policy:
    PolicyDocument: 
      {
        "Statement": [
          {
            "Action": ["ecr:GetAuthorizationToken"],
            "Effect": "Allow",
            "Resource": "*"
          }
        ],
        "Version": "2012-10-17"
      }

stages Array of Maps
Ordered list of environments that your pipeline will deploy to.

stages.name String
The name of an environment to deploy your services to.

stages.requires_approval Boolean
Optional. Indicates whether to add a manual approval step before the deployment (or the pre-deployment actions, if you have added any). Defaults to false.

stages.pre_deployments Map Added in v1.30.0
Optional. Add actions to be executed before deployments.

stages:
  - name: <env name>
    pre_deployments:
      <action name>:
        buildspec: <path to local buildspec>
        depends_on: [<other action's name>, ...]

stages.pre_deployments.<name> Map Added in v1.30.0
Name of the pre-deployment action.

stages.pre_deployments.<name>.buildspec String Added in v1.30.0
The path to a buildspec file, relative to the project root, to use for this build project.

stages.pre_deployments.<name>.depends_on Array of Strings Added in v1.30.0
Optional. Names of other pre-deployment actions that should be deployed prior to deploying this action. Defaults to no dependencies.

Info

For more on pre- and post-deployments, see the v1.30.0 blog post and the Pipelines page.

stages.deployments Map
Optional. Control which CloudFormation stacks to deploy and their order.
The deployments dependencies are specified in a map of the form:

stages:
  - name: test
    deployments:
      <service or job name>:
      <other service or job name>:
        depends_on: [<name>, ...]

For example, if your git repository has the following layout:

copilot
├── api
│   └── manifest.yml
└── frontend
    └── manifest.yml

And you'd like to control the order of your deployments, such that api is deployed before frontend, then you can configure your stage as follows:

stages:
  - name: test
    deployments:
      api:
      frontend:
        depends_on:
          - api

You can also limit which microservices to release part of your pipeline. In the following manifest, we're specifying to deploy only api and not frontend:

stages:
  - name: test
    deployments:
      api:

Finally, if deployments isn't specified, by default Copilot will deploy all your services and job in the git repository in parallel.

stages.deployments.<name> Map
Name of the job or service to deploy.

stages.deployments.<name>.depends_on Array of Strings
Optional. Name of other jobs or services that should be deployed prior to deploying this microservice. Defaults to no dependencies.

stages.deployments.<name>.stack_name String
Optional. Name of the stack to create or update. Defaults to <app name>-<stage name>-<deployment name>.
For example, if your application is called demo, stage name is test, and your service name is frontend then the stack name will be demo-test-frontend.

stages.deployments.<name>.template_path String
Optional. Path to the CloudFormation template generated during the build phase. Defaults to infrastructure/<deployment name>-<stage name>.yml.

stages.deployments.<name>.template_config String
Optional. Path to the CloudFormation template configuration generated during the build phase. Defaults to infrastructure/<deployment name>-<stage name>.params.json.

stages.post_deployments MapAdded in v1.30.0
Optional. Add actions to be executed after deployments. Mutually exclusive with stages.test_commands.

stages:
  - name: <env name>
    post_deployments:
      <action name>:
        buildspec: <path to local buildspec>
        depends_on: [<other action's name>, ...]

stages.post_deployments.<name> Map Added in v1.30.0
Name of the post-deployment action.

stages.post_deployments.<name>.buildspec String Added in v1.30.0
The path to a buildspec file, relative to the project root, to use for this build project.

stages.post_deployments.<name>.depends_on Array of Strings Added in v1.30.0
Optional. Names of other post-deployment actions that should be deployed prior to deploying this action. Defaults to no dependencies.

stages.test_commands Array of Strings
Optional. Commands to run integration or end-to-end tests after deployment. Defaults to no post-deployment validations. Mutually exclusive with stages.post_deployment.