Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Pipeline start conditions
These options allow you to control the start conditions for your pipelines. Restricting your pipelines to start certain conditions (such as, only when a pull request is created or updated) can reduce the number of build minutes used by your team.
Pipelines can be configured to start under different conditions, such as:
Run when a commit is pushed to any branch — The Default start condition.
Run when a commit is pushed to the specified branches — The Branches start condition.
Run when a pull request is created or updated and targeting the specified branches — The Pull Requests start condition.
Run when a Git tag is created — The Tags start condition.
Run when manually started by a user — The Custom start condition.
Pipeline start conditions
Pipelines can be configured to conditionally start using the following options:
The Pipelines property
The pipelines property is used to define the build process for a repository. It includes the pipeline start conditions and pipelines steps. The pipelines property is required and should only be defined once per repository.
Property — pipelines
Required — Yes
Data type — Block (YAML spec - Block Mapping)
Allowed parent properties — The YAML root (pipelines can only be a top-level property)
Allowed child properties — Requires one or more of the default, branches, pull-requests, tags, and custom properties.
Example — using the pipelines properties to create a basic pipeline
1
2
3
4
5
6
pipelines:
default:
- step:
name: Hello world example
script:
- echo "Hello, World!"Default
Contains the pipeline definition for all branches that don't match a pipeline definition in other sections.
The default pipeline runs on every push (excluding tag pushes) to the repository unless a branch-specific pipeline is defined. You can define a branch pipeline in the branches section.
If you ever want to push a commit and skip triggering its pipeline, you can add [skip ci] or [ci skip] to the commit message.
Property — default
Required — No
Data type — List of step, stage, or parallel properties (YAML spec - Sequence)
Allowed parent properties — pipelines
Allowed child properties — Requires one or more of the step, stage, or parallel properties.
Example — using the default property to define a basic pipeline
1
2
3
4
5
6
pipelines:
default:
- step:
name: Hello world example
script:
- echo "Hello, World!"Example — using the default property to with the branches property
The following example shows how to define a default pipeline, to run when the pushed changes are not on a branch prefixed hotfix/.
1
2
3
4
5
6
7
8
9
10
11
12
pipelines:
branches:
hotfix/*:
- step:
name: Build hotfix branch
script:
- echo "Hello, hotfix!"
default:
- step:
name: All other builds
script:
- echo "Hello, World!"Branches
Defines all branch-specific build pipelines. The names or expressions in this section are matched against branches in your Git repository. Glob patterns can be used for matching branches. For information on using glob patterns to match branch names, see Use glob patterns on the Pipelines yaml file.
If you ever want to push a commit and skip triggering its pipeline, you can add [skip ci] or [ci skip] to the commit message.
Property — branches
Required — No
Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)
Allowed parent properties — pipelines
Allowed child properties — User-defined glob patterns matching possible branch names, with step, stage, or parallel elements nested within
Example — using the branches property to define branch-based pipelines
A repository has the following Bitbucket Pipelines configuration in their bitbucket-pipelines.yml:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
image: node:lts
pipelines:
default:
- step:
script:
- echo "This script runs on all branches that don't have any specific pipeline assigned in 'branches'."
branches:
main:
- step:
script:
- echo "This script runs only on commit to the main branch."
feature/*:
- step:
image: openjdk:8 # This step uses its own image
script:
- echo "This script runs only on commit to branches with names that match the feature/* pattern."If the following two branches based on the main branch were pushed to the repository:
feature/BB-123-fix-links — a feature development branch
experimental — a branch containing experimental or innovative change.
The same bitbucket-pipelines.yml file lives in the root directory of each branch. On each push to a branch, Pipelines executes the scripts assigned to that branch in the bitbucket-pipelines.yml file where:
the main branch pipeline definition contains instructions that run when a commit is pushed or merged to the main branch.
the feature/* branches definition contains instructions that run when a commit is pushed to any branch prefixed with feature/, such as the feature/BB-123-fix-links branch.
the default pipeline definition contains instructions that run on a commit to any branch that is not main or prefixed feature/ such as the experimental branch.
Pull Requests
The pull-requests property defines pipelines that only run when a pull request is created. It merges the destination branch into your working branch before it runs. Pull requests from a forked repository don't trigger the pipeline. If the merge fails, the pipeline stops.
Pull request pipelines run in addition to any branch and default pipelines that are defined, so if the definitions overlap you may get 2 pipelines running at the same time.
If you already have branches in your configuration, and you want them all to only run on pull requests, replace the keyword branches with pull-requests. Glob patterns can be used for matching branch names. For information on using glob patterns to match branch names, see Use glob patterns on the Pipelines yaml file.
If you ever want to push a commit and skip triggering its pipeline, you can add [skip ci] or [ci skip] to the commit message.
Property — pull-requests
Required — No
Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)
Allowed parent properties — pipelines
Allowed child properties — User-defined glob patterns matching possible branch names, with step, stage, or parallel elements nested within
Example — using the pull-requests property to run pipelines when a pull request is created
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pipelines:
pull-requests:
feature/*:
- step:
name: Build for feature branch pull request
script:
- echo "Hello, feature branch PR!"
hotfix/*:
- step:
name: Build for hotfix branch pull request
script:
- echo "Hello, hotfix PR!"
'**':
- step:
name: Build for all other pull requests
script:
- echo "Hello, non-feature, non-hotfix pull request!"Example — using the pull-requests and default properties to define a pull request-based pipeline and a default pipeline
Note that both of the following pipelines will run if a branch is prefixed with hotfix/. The default pipeline will start when any branch (including branches prefixed with hotfix/) is pushed to the repository, and the pull request pipeline will start when a pull request is created for matching branches.
1
2
3
4
5
6
7
8
9
10
11
12
pipelines:
pull-requests:
hotfix/*:
- step:
name: Build for hotfix branch pull request
script:
- echo "Hello, hotfix PR!"
default:
- step:
name: All other builds
script:
- echo "Hello, World!"Tags
Defines all tag-specific build pipelines. The names or expressions in this section are matched against tags and annotated tags in your Git repository. Glob patterns can be used for matching tags.
For information on using glob patterns to match branch names, see Use glob patterns on the Pipelines yaml file.
Property — tags
Required — No
Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)
Allowed parent properties — pipelines
Allowed child properties — User-defined glob patterns matching possible git tags, with step, stage, or parallel elements nested within
Example — using the tags property to define tag-based pipelines
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pipelines:
tags:
'*-windows':
- step:
name: Build for *-windows tags
script:
- echo "Hello, Windows!"
'*-macos':
- step:
name: Build for *-macos tags
script:
- echo "Hello, macOS!"
'*-linux':
- step:
name: Build for *-linux tags
script:
- echo "Hello, Linux!"Example — using the tags and default properties to define tag-based pipelines and a default pipeline
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
pipelines:
tags:
'*-windows':
- step:
name: Build for *-windows tags
script:
- echo "Hello, Windows!"
'*-macos':
- step:
name: Build for *-macos tags
script:
- echo "Hello, macOS!"
'*-linux':
- step:
name: Build for *-linux tags
script:
- echo "Hello, Linux!"
default:
- step:
name: Build for all other branches and commits
script:
- echo "Hello, branch or commit!"Custom (manual) pipelines
The custom property is used to define pipelines that can only be triggered manually, or scheduled from the Bitbucket Cloud interface. For details on creating manual or scheduled pipelines, see Create manual and scheduled pipelines.
Property — custom
Required — No
Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)
Allowed parent properties — pipelines
Allowed child properties — User-defined string which will be used as the name of the manual pipeline, with step, stage, parallel, or variables elements nested within
Example — using the custom property to define a manual pipeline named “sonar”
1
2
3
4
5
6
pipelines:
custom: # Pipelines that are triggered manually
sonar: # The name that is displayed in the list in the Bitbucket Cloud GUI
- step:
script:
- echo "Manual triggers for Sonar are awesome!"Example — using the custom property to define two manual pipelines and an automatic pipeline
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pipelines:
custom: # Pipelines that are triggered manually
sonar: # The name that is displayed in the list in the Bitbucket Cloud GUI
- step:
script:
- echo "Manual triggers for Sonar are awesome!"
deployment-to-prod: # Another display name
- step:
script:
- echo "Manual triggers for deployments are awesome!"
branches: # Pipelines that run automatically on a commit to a branch
staging:
- step:
script:
- echo "Auto pipelines are cool too."Custom (manual) pipeline variables
Custom pipeline variables set at run-time are only available for custom pipelines.
Custom pipeline variables allows the defined variables to be set or updated when a custom pipeline is run. Each variable must have a name. Variables can also have a default value and a list of allowed-values. For details on creating manual or scheduled pipelines, see Create manual and scheduled pipelines.
Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.
Property — variables
Required — No
Data type — A list of key-value pairs (YAML spec - Block Mapping)
Allowed parent properties — A manual pipeline name, nested in a custom property
Allowed child properties — name, default, allowed-values, and description
Property | Required or optional | Description | Data Type |
|---|---|---|---|
name | Required | Name of the variable. Used to reference the variable in the pipeline configuration, such as name: Username is referenced in the configuration using $Username. | String |
default | Optional | The default value for the variable. If the variable is not manually set when the pipeline is run, then this value will be used. To define variables that can’t be set at runtime, use User-defined variables. | String |
allowed-values | Optional | A list of values that are allowed for the variable. | List of Strings (YAML spec - Sequence) |
description | Optional | Provides specific information or a short summary to help users know what value(s) to add to properties. | String |
Example — using the variables property to define custom pipeline variables
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pipelines:
custom: # Pipelines that are triggered manually
us-build: # The name that is displayed in the list in the Bitbucket Cloud GUI
- variables:
- name: Username
- name: Role
default: "admin" # optionally provide a default variable value
description: "Add user role"
- name: Region
default: "us-east-1"
allowed-values: # optionally restrict variable values
- "ap-southeast-2"
- "us-east-1"
- "us-west-2"
- step:
script:
- echo "$Username manually triggered for a build for $Region as $Role!"
Was this helpful?