Creating and Configuring Jenkins Multibranch Pipelines

In the previous section a Jenkinsfile that can be checked into source control was implemented. This section introduces the concept of Multibranch Pipelines, which build on the Jenkinsfile foundation to provide more dynamic and automatic functionality in Jenkins.

The Multibranch Pipeline project type enables you to implement different Jenkinsfiles for different branches of the same project. Jenkins automatically discovers, manages, and executes pipelines for branches that contain a Jenkinsfile in source control.

This eliminates the need for manual pipeline creation and management.

To create a Multibranch Pipeline: Click New Item on the Jenkins home page.

Enter a name for your pipeline, select Multibranch Pipeline, and click OK.

Jenkins uses the pipeline name to create directories on disk. Names containing spaces may expose bugs in scripts that do not expect spaces in paths.

Add a Branch Source (e.g., Git) and enter the repository location.

Save the Multibranch Pipeline project.

Upon saving, Jenkins automatically scans the designated repository and creates items for each branch that contains a Jenkinsfile.

By default, Jenkins will not automatically re‑index the repository for branch additions or deletions (unless using an Organization Folder), so it is often useful to configure a Multibranch Pipeline to periodically re‑index in the configuration.

Additional Environment Variables

Multibranch Pipelines expose additional information about the branch being built through the env global variable, such as:

BRANCH_NAME – Name of the branch for which this pipeline is executing, e.g., master .

CHANGE_ID – Identifier corresponding to a change request, such as a pull‑request number.

Additional environment variables are listed in the Global Variable Reference.

Supporting Pull Requests

Multibranch Pipelines can validate pull/change requests with the appropriate plugin. The following plugins provide this functionality:

GitHub Branch Source

Bitbucket Branch Source

GitLab Branch Source

Gitea

Tuleap Git Branch Source

AWS CodeCommit Jobs

DAGsHub Branch Source

Please consult the plugin documentation for further information on how to use them.

Using Organization Folders

Organization Folders enable Jenkins to monitor an entire GitHub Organization, Bitbucket Team/Project, GitLab organization, or Gitea organization and automatically create new Multibranch Pipelines for repositories that contain branches and pull requests with a Jenkinsfile.

Organization folders are implemented for:

GitHub in the GitHub Branch Source plugin

Bitbucket in the Bitbucket Branch Source plugin

GitLab in the GitLab Branch Source plugin

Gitea in the Gitea plugin