A multibranch pipeline enables development teams to maintain discrete pipelines for different branches of the same project. The pipeline of each branch will have its own run history and logs.
Many development organizations use a branching model (such as GitFlow) for collaboration on large projects. In this style of workflow, development teams maintain a main source code branch while creating feature branches for each feature in-progress. The feature team will merge those changes into the main branch when feature development is complete, and delete the feature branch.
In this agile development model, feature branches are created and destroyed frequently. Manually administering each branch as a new pipeline source can be a slow and annoying chore.
When you designate a pipeline source as multibranch, Pipelines automatically creates a new pipeline from each branch's pipeline config, and destroys the pipeline when the branch is destroyed. In this way, the main branch and included child branches will all have their own pipeline, each of which can be independently viewed, run, and triggered.
Configuring a Multibranch Pipeline Source
A multibranch pipeline must be in a pipeline source that has been configured as multibranch.
When a multibranch pipeline source syncs, it automatically creates and destroys pipeline config files in branches from the main branch. You can specify Exclude and Include Branch Patterns to limit which branches participate in automatic pipeline creation/deletion.
For more information, see Managing Pipeline Sources.
Declaring a Multibranch Pipeline
In Pipelines DSL, the term {{gitBranch}} can be used as a placeholder for whatever branch the pipeline was loaded from. When Pipelines syncs from the pipeline source, it automatically replaces any occurrence of {{gitBranch}} with the name of the branch. Note that this will occur for single branch pipeline sources as well as multbranch ones).
When creating a multibranch pipeline in Pipelines DSL, use {{gitBranch}} as the value anywhere you would designate a branch. When Pipelines syncs each of the branches of a multibranch pipeline source, it will automatically replace the {{gitBranch}} reference in each branch's pipeline with the name of its branch.
In the GitRepo resource definition, use {{gitBranch}} where you define the branches of that resource to include.
pipelines_resources.yml
resources:
- name: appRepo
type: GitRepo
configuration:
gitProvider: my_github
path: myrepo/myproject
branches:
include: ^{{gitBranch}}$ # Formatted as a regex pattern
You can also use{{gitBranch}} anywhere you might refer to a branch in steps or pipeline configuration. This example pipeline outputs the name of the branch.
pipelines_steps.yml
pipelines:
- name: multibranch_example
steps:
- name: mb_step_1
type: Bash
configuration:
affinityGroup: together
inputResources:
- name: appRepo
execution:
onExecute:
- echo "running test for branch {{gitBranch}}"
- pushd $res_tw_multibranch_repo_resourcePath
- ls -latr
- popd
- name: mb_step_2
type: Bash
configuration:
affinityGroup: together
inputSteps:
- name: mb_step_1
execution:
onExecute:
- echo "building {{gitBranch}}"
Note
When used in a conditional or comparison logic, {{gitBranch}} placeholders must be wrapped within double quotes.
Example: {{ if eq "{{gitBranch}}" "master" }}
Running Multibranch Pipelines
A multibranch pipeline synced from a multibranch pipeline source appears in My Pipelines as an expandable entry in the list. Click to expand a multibranch pipeline source and then click one of the branch versions to view and run it.