Stages

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 deployment steps.

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

Stage properties

Stages can have the following properties in addition to the required steps property.

Required properties:

Optional properties:

Require properties

Steps

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

Propertysteps

Required — Yes

TypeBlock sequence (also known as a list)

Possible valuesstep: (for details, see step)

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

 

Optional properties

Condition

The condition property allows a stage only to execute when a condition or rule is satisfied. All steps within the stage will have the same condition.

For details about conditions, see Step condition.

Propertycondition

Required — No (optional property)

TypeMapping Node

Possible valueschangesets: (for details, see condition)

Example
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 and is used to organize the Deployment dashboard. All steps that belong to the Deployment stage will be a Deployment step.

For details on Deployment stages, see Deployment stages.

Propertydeployment

Required — No (optional property)

Type — String

Possible values — The name of an existing deployment environment.

Example
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 stage. The stage's name will be shown in the Bitbucket Pipeline logs and the Bitbucket UI. Names should be unique (within the pipeline) and describe the steps in the stage.

Propertyname

Required — No (optional property)

Type — String

Possible values — Any string

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

 

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.

Propertytrigger

Required — No (optional property)

Type — String

Default valueautomatic

Possible valuesautomatic or manual

Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - 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

 

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.

Additional Help