Stage options

This feature is currently in Beta and may be subject to change. For terms and conditions, see section 14 (Evaluations, trials, and betas) of the Atlassian Cloud Terms of Service.

Stages allow you to group pipeline steps logically with shared properties, such as grouping steps for the same deployment environment.

Overview

Setting up stages

To add a stage to your pipeline, add the stage property and group one or more steps within that stage. For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 pipelines: default: - stage: name: Build and test steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Use Stages for deployments

Using deployment stages allows you to:

  • Combine steps to form a logically structured deployment.

  • Easily see which part of a deployment failed.

  • Rerun only the failed part of the deployment, rather than doing a full redeploy.

Deployment stages will also benefit from deployment permissions and concurrency control.

To create a deployment stage:

  1. Add a stage to the pipeline

  2. Add the deployment property to the stage

  3. Add the appropriate steps to the stage.

For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 pipelines: default: - step: name: Build and test script: - sh ./build-app.sh - stage: name: Deploy to staging deployment: staging steps: - step: name: Deploy script: - sh ./deploy-app.sh - step: name: Run end-to-end tests script: - sh ./run-e2e-tests.sh

This deployment stage consists of two steps:

  1. The first step deploys the app to the staging environment.

  2. The second step then runs end-to-end tests against the staging environment, checking that the deployment did not cause any issues.

Rerunning an incomplete deployment stage

Rerunning a failed, paused, or stopped step within a deployment stage is similar to rerunning a step, but there are some additional conditions:

  • The pipeline artifacts need to be still available (not expired).

  • A step within a stage can only be rerun if there hasn't been a newer or later deployment in the same environment.

Redeploying a deployment stage

To redeploy a previously successful deployment stage:

  • Ensure the pipeline artifacts need to be still available (not expired).

  • Rerun the entire deployment stage.

Rerunning an incomplete redeployment of a deployment stage

To rerun a failed or stopped step within a deployment stage:

  • The pipeline artifacts need to be still available (not expired).

  • A step within a stage can only be rerun if there hasn't been a newer or later deployment in the same environment. A stage can still be redeployed from the first step.

Limitations

  • The maximum number of steps you can within a stage is:

  • Parallel stages are not supported.

  • A stage can't include parallel steps.

  • A stage can't contain manually triggered steps, but you can configure a stage to be manually triggered.

  • A stage can't contain conditional steps, but you can configure a stage to be conditional.

  • Disabling artifact downloads inside a stage is not supported.

  • Steps can't override any property also set on a stage.

  • Partially completed deployment stages can't be continued if another change was subsequently deployed to the same environment.

Stage options

The following options can be used to configure stages:

Stage

Stages allow you to group pipeline steps with shared properties. For example, you can use a stage to group the steps required for a deployment (such as deploying an app and checking the deployment was successful).

For information on creating and using Pipelines Stages, see Stages.

Propertystage

Required — No

Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)

Allowed parent propertiesdefault, branches, pull-requests, tags, and custom

Allowed child propertiessteps (required), name, deployment, trigger, and condition

Example — using stage to group pipeline steps

1 2 3 4 5 6 7 8 9 10 11 12 13 pipelines: default: - stage: name: Build and test steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Steps

The steps property contains the lists of steps in a stage or a parallel. At least 1 step is required within the steps list.

Propertysteps

Required — Yes

Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)

Allowed parent propertiesparallel and stage

Allowed child propertiesstep (required)

Example — using the steps property to list the steps in a parallel group

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 pipelines: default: - step: # sequential step name: Build script: - ./build.sh - step: # sequential step name: Build script: - ./build.sh - parallel: # these 2 steps will run in parallel steps: - step: name: Integration 1 script: - ./integration-tests.sh --batch 1 - step: name: Integration 2 script: - ./integration-tests.sh --batch 2 - step: # non-parallel step script: - ./deploy.sh

Example — using the steps property to list the steps in a stage

1 2 3 4 5 6 7 8 9 10 11 12 13 pipelines: default: - stage: name: Build and test steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Condition

The condition option prevents a step or stage from running unless a condition or rule is satisfied. Currently, the only condition supported is changesets. Use changesets to execute a step or stage only if one of the modified files matches the expression in includePaths. The file match pattern specified in the includePaths is relative to the $BITBUCKET_CLONE_DIR directory.

Changes that are taken into account

In a pull-requests pipeline, all commits are taken into account, and if you provide an includePath list of patterns, the step or stage will be executed when at least one commit change matches one of the conditions. The format for pattern matching follows the glob patterns.

For other types of pipelines, only the last commit is considered. If you push multiple commits to branch at the same time or if you push multiple times to given branch, you might experience non-intuitive behavior when failing pipelines turn green only because the failing step or stage is skipped on the next run.

Propertycondition

Required — No

Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)

Allowed parent propertiesstep and stage

Allowed child propertieschangesets (required)

Example — using the condition option to only run a step when certain files change

1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - step: name: step1 script: - echo "failing paths" - exit 1 condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**"

Example — using the condition option to only run a stage when certain files change

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 pipelines: default: - stage: name: Build and test condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**" steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Changesets

The changesets option is used to indicate that the condition for a step or stage is a change in a particular file or files (includePaths).

Propertychangesets

Required — Required when using the condition option.

Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)

Allowed parent propertiescondition

Allowed child propertiesincludePaths (required)

Example — using the condition option to only run a step when certain files change
1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - step: name: step1 script: - echo "failing paths" - exit 1 condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**"
Example — using the condition option to only run a stage when certain files change
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 pipelines: default: - stage: name: Build and test condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**" steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh
includePaths

When used with the condition and changesets options, the includePaths option allows you to provide a list of files or directories to check for changes. If a file in the list is changed by a commit, the step or stage will run, otherwise the step will be skipped.

PropertyincludePaths

Required — No

Data type — A list of file paths (glob patterns are allowed) (YAML spec - Sequence)

Allowed parent propertieschangesets

Example — using the condition option to only run a step when certain files change
1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - step: name: step1 script: - echo "failing paths" - exit 1 condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**"
Example — using the condition option to only run a stage when certain files change
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 pipelines: default: - stage: name: Build and test condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**" steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Deployment

Sets the environment for a Deployment stage or step and is used to organize the Deployment dashboard. All steps that belong to the Deployment stage will be a Deployment step. The default environments are: test, staging, or production. To set the deployment environment of a step or stage, include the Environment name.

For details on:

Propertydeployment

Required — No

Data type — String

Allowed values — The name of a Deployment environment

Allowed parent propertiesstep and stage

Example — using deployment to set the deployment environment for a step

1 2 3 4 5 6 7 pipelines: default: - step: name: Deploy to production deployment: production env 1 script: - python deploy.py prod_env_1

Example — using deployment to set the deployment environment for stages

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 pipelines: default: - stage: name: Build and test deployment: staging steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh - stage: name: Deploy to Production deployment: prod trigger: manual steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Name

A name for the step, stage, or pipe. The name will be shown in the Bitbucket Pipeline logs and the Bitbucket UI. Names should be unique (within the pipeline) and describe the step or the steps in the stage.

Propertyname

Required — No

Data type — String

Allowed parent propertiesstep, pipe, and stage

Example — using name to label a stage, a pipe, and two steps

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 pipelines: default: - stage: name: Build and test steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh - step: script: - pipe: atlassian/slack-notify:latest name: Send a message to Slack variables: WEBHOOK_URL: $SLACK_WEBHOOK PRETEXT: 'Hello, Slack!' MESSAGE: 'Hello, Slack!!'

Trigger

Sets the stage to run automatically (default behavior) or only when manually triggered by a user in the Bitbucket user interface. The first stage in a pipeline can't be manual. To set a whole pipeline to run manually, use a custom pipeline trigger. Manual steps and stages:

  • Can’t be the first step or stage in a pipeline.

  • Can only be executed in the order that they are configured. You cannot skip a manual step or stage.

  • Can only be executed if the previous step or stage has successfully completed.

  • Can only be triggered by users with write access to the repository.

  • Are triggered through the Pipelines web interface.

If your build uses both manual steps and artifacts, the artifacts are stored for 14 days following the execution of the step that produced them. After this time, the artifacts expire and any manual steps and manual stages in the pipeline can no longer be executed.

Propertytrigger

Required — No

Data type — String

Allowed valuesautomatic and manual

Default valueautomatic

Allowed parent propertiesstep and stage

Example — using trigger to set a step to manual

1 2 3 4 5 6 7 8 9 10 11 12 13 pipelines: default: - step: name: Build script: - npm run build artifacts: - dist/** - step: name: Deploy trigger: manual script: - ./deploy.sh

Example — using trigger to set a stage to manual

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 pipelines: default: - stage: name: Linting steps: - step: script: - sh ./run-linter.sh - stage: name: Build and test trigger: manual steps: - step: name: Build app script: - sh ./build-app.sh - step: name: Run unit tests script: - sh ./run-tests.sh

Additional Help