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:

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

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:

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: