Stage options

Stages allow you to group pipeline steps logically with shared properties, such as grouping steps for the same deployment environment, locking a deployment environment for multiple steps (preventing other Pipeline runs from interacting with it), and sharing deployment variables across multiple sets of sequential steps.

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:

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.
Share Deployment Variables over multiple steps within the same stage.
Maintain a lock over a Deployment Environment over multiple steps within the same stage.

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

To create a deployment stage:

Add a stage to the pipeline
Add the deployment property to the stage
Add the appropriate steps to the stage.

For example:

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:

The first step deploys the app to the staging environment.
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:
- 10 steps for workspaces on the Free plan.
- 100 steps for workspaces on a Standard or Premium plan.
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

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.

Property — stage

Required — No

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

Allowed parent properties — default, branches, pull-requests, tags, and custom

Allowed child properties — steps (required), name, deployment, trigger, and condition

Example — using stage to group pipeline steps

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.

Property — steps

Required — Yes

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

Allowed parent properties — parallel and stage

Allowed child properties — step (required)

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

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

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.

Property — condition

Required — No

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

Allowed parent properties — step and stage

Allowed child properties — changesets (required)

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

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

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).

Property — changesets

Required — Required when using the condition option.

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

Allowed parent properties — condition

Allowed child properties — includePaths (required)

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

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

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.

Property — includePaths

Required — No

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

Allowed parent properties — changesets

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

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

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:

deployment stages, see Deployment stages.
creating and configuring deployment environments, see Set up and monitor deployments.

Property — deployment

Required — No

Data type — String

Allowed values — The name of a Deployment environment

Allowed parent properties — step and stage

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

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

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 or stage. 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.

Property — name

Required — No

Data type — String

Allowed parent properties — step and stage

Example — using name to label a stage and two steps

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

Property — trigger

Required — No

Data type — String

Allowed values — automatic and manual

Default value — automatic

Allowed parent properties — step and stage

Example — using trigger to set a step to manual

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

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

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community