Bitbucket allows you to run multiple pipelines by triggering them manually or by scheduling the trigger at a given time.
Tutorial
In the following tutorial, you’ll learn how to trigger manual pipelines or how to schedule triggers.
Before you begin
Triggers in Pipelines have the following limitations:
Run pipelines steps manually
Manual steps allow you to customize your CI/CD pipeline by making some steps run only if they are manually triggered. This is useful for items such as deployment steps, where manual testing or checks are required before the step runs.
Configure a manual step by adding trigger: manual to the step in your bitbucket-pipelines.yml file.
Since a pipeline is triggered on a commit, you can't make the first step manual. If you'd like a pipeline to only run manually, you can set up a custom pipeline instead. Another advantage of a custom pipeline is that you can temporarily add or update values for your variables, for example, to add a version number, or supply a single-use value.
Set a manual pipelines
Any existing pipeline can also be manually run against a specific commit, or as a scheduled build.
If you want a pipeline to only run manually then use a custom pipeline. Custom pipelines donot run automatically on a commit to a branch. To define a custom pipeline, add the pipeline configuration in the custom section of your bitbucket-pipelines.yml file. Pipelines which are not defined as a custom pipeline will also run automatically when a push to the branch occurs.
You'll need write permission on the repository to run a pipeline manually, and you can trigger it from the Bitbucket Cloud UI.
Steps
Add a pipeline to the bitbucket-pipelines.yml file. You can manually trigger a build for any pipeline build configuration included in your bitbucket-pipelines.yml file
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pipelines:
custom: # Pipelines that can only be triggered manually
sonar:
- step:
script:
- echo "Manual triggers for Sonar are awesome!"
deployment-to-prod:
- step:
script:
- echo "Manual triggers for deployments are awesome!"
branches: # Pipelines that run automatically on a commit to a branch can also be triggered manually
staging:
- step:
script:
- echo "Automated pipelines are cool too."
Trigger the pipeline from Bitbucket Cloud. Pipelines can be triggered manually from either the Branches view or the Commits view in the Bitbucket Cloud interface.
Run a pipeline manually from the Branches view
In Bitbucket, choose a repo and go to Branches.
Choose the branch you want to run a pipeline for.
Click (...) , and select Run pipeline for a branch.
Choose a pipeline and click Run:
Run a pipeline manually from the Commits view
In Bitbucket, choose a repo and go to Commits.
Go to the Commits' view for a commit.
Select a commit hash.
Select Run pipeline.
Choose a pipeline, then click Run:
Run a pipeline manually from the Pipelines page
In Bitbucket, choose a repo and go to Pipelines.
Click Run pipeline
Choose branch, a pipeline, and click Run
Additionally, you can run custom pipelines manually parsing variables to the pipeline. To enable the variables, define them under the custom pipeline that you want to enter when you run the pipeline.
Example:
1
2
3
4
5
6
7
8
9
10
pipelines:
custom:
custom-name-and-region: #name of this pipeline
- variables: #list variable names under here
- name: Username
- name: Region
- step:
script:
- echo "User name is $Username"
- echo "and they are in $Region"
Then, when you run a custom pipeline by going to Branches > ⋯ > Run pipeline for a branch > Custom.
On schedule
Scheduled pipelines allow you to run a pipeline at hourly, daily or weekly intervals.
Scheduled pipelines run in addition to any builds triggered by commits, or triggered manually.
You can create a schedule for any pipeline defined in your bitbucket-pipelines.yml file.
If you make a custom pipeline it will only run when scheduled or manually triggered.
Steps
Create a pipeline
Here's a simple example showing how you would define a custom pipeline in the bitbucket-pipelines.yml file.
Example:
1
2
3
4
5
6
pipelines:
custom: # defines that this can only be triggered manually or by a schedule
staging: # The name that is displayed in the list in the Bitbucket Cloud GUI
- step:
script:
- echo "Scheduled builds in Pipelines are awesome!"
Click Pipelines then Schedules (at the top right), and then click New schedule.
Choose the Branch and Pipeline that you want to schedule:
The schedule will run the HEAD commit of the branch.
The pipeline must be defined in the bitbucket-pipelines.yml on the branch you selected.
Set the Schedule:
Select how often you would like the pipeline to run (hourly, daily or weekly)
Select the time (in your local time). However, your pipeline will be scheduled in UTC time (unaffected by daylight savings hours)
The scheduled pipeline can run at any time in the selected time period. This is to distribute all schedules in Pipelines triggering across the hour.
Remove a schedule
Go to Pipelines > Schedules (at the top right-hand side of the screen) to see all the schedules for a repository.
Remove a schedule by using the 'trash' icon at the right of the schedule.
Note that schedules created using the API are displayed as a Cron expression (such as 0 10 15 * *).
Branch workflows
You can change what your pipeline does depending on which branch you push to. All you need is some branch-specific configuration in your bitbucket-pipelines.yml file.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
image: node:10.15.0
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."
That example shows two branches based on the main branch:
a branch called feature/BB-123-fix-links that is a feature branch
a branch called experimental where your team can go crazy innovating and breaking stuff. This branch is not a feature branch.
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:
main step definition contains instructions that run on a commit to main
feature/* definition contains instructions that run on a commit to any feature branch (that's our BB-123-fix-links branch)
default definition contains instructions that run on a commit to any branch that is not main or feature (that's our experimental branch)
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.
Keywords
Default branches: Contains the pipeline definition for all branches that don't match a pipeline definition in other sections. The default pipeline runs on every push to the repository unless a branch-specific pipeline is defined. You can define a branch pipeline in the branches section.
Note: The default pipeline doesn't run on tags or bookmarks.
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.
Example:
This tag triggers a pipeline when a tag starting with “release-” is pushed.
1
2
3
4
5
6
pipelines:
tags:
release-*:
- step:
script:
- echo "A tag triggered build"
pull-request: A special pipeline that only runs on pull requests initiated from within your repo. 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.
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pipelines:
pull-requests:
'**': #this runs as default for any branch not elsewhere defined
- step:
script:
- ...
feature/*: #any branch with a feature prefix
- step:
script:
- ...
branches: #these will run on every push of the branch
staging:
- step:
script:
- ...
custom: Defines pipelines that can only be triggered manually or scheduled from the Bitbucket Cloud interface.
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
image: node:10.15.0
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."
With a configuration like the one above, you should see the following pipelines in the Run pipeline dialog in Bitbucket Cloud:
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
image: node:10.15.0
pipelines:
default:
- step:
name: Build and test
script:
- npm install
- npm test
tags: # add the 'tags' section
release-*: # specify the tag
- step: # define the build pipeline for the tag
name: Build and release
script:
- npm install
- npm test
- npm run release
branches:
staging:
- step:
name: Clone
script:
- echo "Clone all the things!"
variables [Custom pipelines only] Contains variables that are supplied when a pipeline is launched. To enable the variables, define them under the custom pipeline that you want to enter when you run the pipeline:
Example:
1
2
3
4
5
6
7
8
9
10
pipelines:
custom:
custom-name-and-region: #name of this pipeline
- variables: #list variable names under here
- name: Username
- name: Region
- step:
script:
- echo "User name is $Username"
- echo "and they are in $Region"
Then, when you run a custom pipeline (Branches > ⋯ > Run pipeline for a branch > Custom:..) you'll be able to fill them in.
The keyword variables can also be part of the definition of a service.
bookmarks: Defines all bookmark-specific build pipelines. The names or expressions in this section are matched against bookmarks in your Mercurial repository.
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
image: node:10.15.0
pipelines:
default:
- step:
name: Build and test
script:
- npm install
- npm test
bookmarks: # add the 'bookmarks' section
release-*: # specify the bookmark
- step: # define the build pipeline for the bookmark
name: Build and release
script:
- npm install
- npm test
- npm run release
branches:
staging:
- step:
name: Clone
script:
- echo "Clone all the things!"
Glob patterns
Glob patterns don't allow any expression to start with a star. Every expression that starts with a star needs to be put in quotes.
feature/*
Matches with feature/<any_branch>.
The glob pattern doesn't match the slash ( /), so Git branches like feature/<any_branch>/<my_branch> are not matched for feature/*.
feature/bb-123-fix-links
If you specify the exact name of a branch, a tag, or a bookmark, the pipeline defined for the specific branch overrides any more generic expressions that would match that branch. For example, let's say you specify a pipeline for feature/* and feature/bb-123-fix-links. On a commit to the feature/bb-123-fix-links branch, Pipelines executes the steps defined for feature/bb-123-fix-links and won't execute the steps defined in the feature/*.
' * '
Matches all branches, tags, or bookmarks. The star symbol ( * ) must be between single quotes.
This glob pattern doesn't match the slash (/ ), so Git branches like feature/bb-123-fix-links are not matched for '*'. If you need the slash to match, use '**' instead of '*'.
' ** '
Matches all branches, tags, or bookmarks. For example, it includes branches with the slash ( /) like feature/bb-123-fix-links. The ** expression must be in quotes.
' */feature '
This expression requires quotes.
' main ' and duplicate branch names
Names in quotes are treated the same way as names without quotes. For example, Pipelines sees main and ' main ' as the same branch names.
In the situation described above, Pipelines will match only against one name (main or ' main', never both).
Try to avoid duplicating names in your bitbucket-pipelines.yml file.
