Creating Multibranch Pipelines

Overview

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.

Page Contents

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}}"

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.

With your branch chosen, you can view the Pipeline Run Logs of any run in that branch.

The example multibranch pipeline above uses {{gitBranch}} to output the name of the branch being run. You can see the results of this in the run logs of the pipeline in each branch.

Content

Space Tools

Creating Multibranch Pipelines

Overview

Configuring a Multibranch Pipeline Source

Declaring a Multibranch Pipeline

Running Multibranch Pipelines