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.

Propertypipelines

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.

Propertydefault

Required — No

Data type — List of step, stage, or parallel properties (YAML spec - Sequence)

Allowed parent propertiespipelines

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.

Propertybranches

Required — No

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

Allowed parent propertiespipelines

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.

Propertypull-requests

Required — No

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

Allowed parent propertiespipelines

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.

Propertytags

Required — No

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

Allowed parent propertiespipelines

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.

Propertycustom

Required — No

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

Allowed parent propertiespipelines

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.

Propertyvariables

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 propertiesname, 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!"

 

Still need help?

The Atlassian Community is here for you.