Pipeline start conditions

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

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.

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

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

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.

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:

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.

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. Note: The assigned branch must be the source branch of the pull request.

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.

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

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.

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

Example — using the tags and default properties to define tag-based pipelines and a default pipeline

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”

Example — using the custom property to define two manual pipelines and an automatic pipeline

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.

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

Example — using the variables property to define custom pipeline variables

The triggers property enables you to define condition-based rules that can trigger multiple pipelines in parallel from a single event. Unlike the traditional selector-based approach, which uses branches, tags, or pull-requests to select a single pipeline, triggers use logical expressions to determine which pipelines should run, allowing for more flexible and powerful configurations.

With the triggers property, you can:

• Run pipelines in parallel, independently from a single event

• Use logical expressions for complex conditions

• Trigger multiple pipelines from a single event

• Decouple large, monolithic pipelines into smaller, focused ones

Property — triggers

Required — No

Data type — Block (YAML spec - Block Mapping)

Allowed parent properties — The YAML root (triggers can only be a top-level property)

Allowed child properties — Trigger type, with a list of condition definitions nested within.

Example — using the triggers property to configure two pipelines to run when the “main” branch is pushed:

This example runs both pipeline1 and pipeline2 in parallel when a commit is pushed to the main branch.

Example — using the triggers property to configure two pipelines to run when the “main” branch has a pull request created or updated:

This example runs both pipelines when a pull request involving the main branch is created or updated.

The trigger type specifies the repository event (such as a push or pull request update) that causes Bitbucket to evaluate the associated conditions. If a condition evaluates to true, the specified pipelines are run.

Supported trigger types:

• repository-push
  Evaluated when a commit is pushed to any branch, or when a git tag is created.

• pullrequest-push
  Evaluated when a pull request is created or updated.

Required — No

Data type — String

Allowed values — repository-push, pullrequest-push

Allowed parent properties — triggers

Allowed child properties — condition, pipelines

The condition property defines a logical expression that is evaluated at runtime to determine whether the specified pipelines should be triggered. Conditions can use pipeline variables and support logical operators for flexible matching.

Property — condition

Required — Yes

Data type — String

Allowed parent properties — Must be nested under a trigger type within triggers

Allowed child properties — none

Example – Trigger a pipeline when a pull request is created or updated, with the source branch as “feature/test” and the destination branch as “main”:

This example triggers pipeline1 only when a pull request is created or updated from the feature/test branch to the main branch.

The pipelines property specifies which pipelines are triggered when the associated condition evaluates to true. All pipelines listed here are started in parallel.

Property — pipelines

Required — Yes

Data type — List of Strings (YAML spec - Sequence)

Allowed parent properties — Must be nested under a condition within a trigger type in triggers

Allowed child properties — none

Example – Trigger two pipelines in parallel when a commit is pushed to the “main” branch:

This example triggers both pipeline1 and pipeline2 in parallel when a commit is pushed to the main branch.

Trigger conditions use logical expressions to determine which pipelines should run for a given event. Each condition is evaluated at runtime using available pipeline variables. If the condition evaluates to true, the associated pipelines are triggered.

The following variables can be used in condition expressions:

• BITBUCKET_BRANCH — The name of the branch for the event.

• BITBUCKET_TAG — The name of the tag for the event.

• BITBUCKET_PR_DESTINATION_BRANCH — The destination branch of the pull request.

• BITBUCKET_PR_DESTINATION_COMMIT — The commit hash at the destination of the pull request.

• BITBUCKET_PR_ID — The ID of the pull request.

• All non-secure workspace and repository variables

Guidelines:

• Variables should appear in the condition expression without quotation marks (e.g., BITBUCKET_BRANCH).

• String literals should be surrounded by quotation marks (e.g., "main").

• Boolean and numbers are supported and can be provided without quotes.

• All comparisons are case-sensitive.

• Variables are case-sensitive and must be used as shown.

Supported Operators:

• == — Equality

• != — Inequality

• && — Logical AND

• || — Logical OR

• ! — Logical NOT

• () — Grouping

• >, >=, <, <= — Comparison operators

• glob(value, pattern) — Pattern matching using glob syntax

Examples:

• Simple equality:
  condition: BITBUCKET_BRANCH == "main"
  Runs when the branch is exactly "main".

• Glob pattern matching:
  condition: glob(BITBUCKET_BRANCH, "feature/*")
  Runs for any branch starting with "feature/".

• Complex logical expressions:
  condition: BITBUCKET_BRANCH == "main" && BITBUCKET_PR_DESTINATION_BRANCH == "production"
  Runs when the branch is "main" and the PR destination is "production".

• Using OR:
  condition: BITBUCKET_BRANCH == "integration" || BITBUCKET_PR_DESTINATION_BRANCH == "main"
  Runs if the branch is "integration" or the PR destination is "main".

• Using NOT:
  condition: !(glob(BITBUCKET_BRANCH, "feature/*") || BITBUCKET_BRANCH == "main")
  Runs for branches that are not "main" and do not match "feature/*".

The glob() function enables flexible pattern matching in trigger conditions, allowing you to match branches, tags, or other variables using wildcards and brace expansion. It returns true if the value matches the pattern, and false otherwise.

Syntax and parameters

Syntax: glob(value, "pattern")

• value: The variable to test (e.g., BITBUCKET_BRANCH, BITBUCKET_TAG)

• pattern: The glob pattern to match (must be in quotes; supports wildcards like *, ?, and brace expansion {}; patterns are case-sensitive)

Behavior

The glob() function follows the same pattern-matching rules as using glob patterns on the Pipelines yaml file.

You can combine glob() with logical operators (&&, ||, !) in condition expressions for advanced matching.

Examples:

• Match feature branches:
  glob(BITBUCKET_BRANCH, "feature/*")
  Matches any branch that starts with "feature/".

• Match version tags:
  glob(BITBUCKET_TAG, "v1.*")
  Matches tags like "v1.0", “v1.1” etc

• Match multiple patterns using brace expansion:
  glob(BITBUCKET_BRANCH, "{main,develop,staging}")
  Matches if the branch is "main", "develop", or "staging".

• Match all with glob **:
  glob(BITBUCKET_BRANCH, "**")
  Matches any branch name.

The following limitations apply for triggers:

• Maximum of 20 conditions per trigger type (e.g., up to 20 for repository-push and 20 for pullrequest-push) per YAML file.

• Maximum of 100 pipelines can be triggered from a single event (across all matching conditions and trigger types).

• All pipelines referenced in triggers must be defined in the custom section of your YAML file.

• Imported pipelines are supported (e.g., pipelines included via YAML imports), but they must still be defined in the custom pipelines.)