Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 40 ยท Source Control and Triggers

Multibranch Pipelines and Pull Requests

Let Jenkins discover branches, pull requests and tags by itself: branch sources, behaviors, organization folders, build strategies and orphaned item cleanup.

A single pipeline job builds one branch. Real projects have many: main, a release branch, a dozen feature branches and a stream of pull requests. Creating and deleting a job for each by hand would be a full-time job. A multibranch pipeline solves this: you point Jenkins at a repository once, and it creates a child job for every branch (and optionally every pull request and tag) that contains a Jenkinsfile. When a branch is deleted, its job goes away too.

This lesson covers branch sources, discovery behaviors, pull request builds, organization folders, build strategies, tag builds and cleanup. The real Jenkins cannot run on this site, so configuration is shown read-only, and the runnable examples are stand-ins written in JavaScript.

One repo, many jobs

Branches Each branch with a Jenkinsfile gets a job.
Pull requests Built as the merge result or the head.
Tags Optional, for release builds.

Jenkins scans the repository to find them.

1 / 2

What a multibranch job is

A multibranch job is a folder of jobs. It has two parts you configure:

  1. A branch source: where the code lives (GitHub, GitLab, Bitbucket, or a plain Git URL) and which credentials to use.
  2. Behaviors that say what to discover and what to ignore.

Jenkins runs a branch indexing (also called a scan): it lists the branches, checks each one for a file named Jenkinsfile (the path is configurable), and creates, updates or removes the child jobs. Every child job is an ordinary pipeline whose definition is the Jenkinsfile on that branch. The effect is powerful: a developer can change the build in a feature branch, and only that branch's builds change.

Scans run when a webhook arrives and, as a fallback, on a periodic schedule. The log of the last scan is on the multibranch job's page and is the first place to look when a branch does not show up.

Branch sources and behaviors

Typical behaviors you can switch on:

  • Discover branches: all branches, only branches that are not pull requests, or only those that are.
  • Discover pull requests from origin: pull requests whose source branch lives in the same repository.
  • Discover pull requests from forks: pull requests from forks, with a trust policy that decides whose changes may use your Jenkinsfile and credentials.
  • Discover tags: tags become jobs, useful for release pipelines.
  • Filter by name: include or exclude branches by pattern, such as main release/* feature/*.
  • Clean before/after checkout, shallow clone and other Git options from Checking Out Code with Git.

The trust policy deserves attention. A pull request from a stranger's fork can modify the Jenkinsfile, which runs on your agents with your tools. The safe defaults trust only contributors with write access, and build the Jenkinsfile from the target branch for untrusted changes. Never relax this on a public repository without understanding the consequences.

Pull request builds

A pull request can be built in two ways, and plugins let you choose or build both:

  • the head of the pull request branch, as the author pushed it;
  • the merge result: what the target branch would look like after merging.

The merge result is a better test of what will really happen, because the target may have moved on. Inside the pipeline, these variables describe the situation:

Variable Meaning
BRANCH_NAME the branch, or something like PR-42 for a pull request
CHANGE_ID the pull request number (empty on normal branches)
CHANGE_TARGET the branch the pull request wants to merge into
CHANGE_BRANCH the source branch of the pull request
TAG_NAME the tag name, when a tag is being built

Use them in when conditions to give each kind of build the right stages:

GROOVY
pipeline {
  agent any
  stages {
    stage('Build and test') {
      steps { sh './gradlew build' }
    }
    stage('Publish snapshot') {
      when { branch 'main' }
      steps { sh './gradlew publishSnapshot' }
    }
    stage('Preview deploy') {
      when { changeRequest target: 'main' }
      steps { sh './deploy-preview.sh "PR-${CHANGE_ID}"' }
    }
    stage('Release') {
      when { buildingTag() }
      steps { sh './release.sh "${TAG_NAME}"' }
    }
  }
}

The when conditions themselves are covered in Conditions and Post Actions.

Organization folders

An organization folder goes one step further. You point it at a GitHub organization, a GitLab group or a Bitbucket team, and Jenkins scans every repository, creating a multibranch folder for each repository that has a Jenkinsfile. When a team creates a new service with a Jenkinsfile, CI appears automatically with no admin involved. Repositories without a Jenkinsfile are skipped.

This is a great fit for companies with many small repositories. It does mean that the Jenkinsfile in every repository runs on your agents, so combine it with sensible agent isolation and credential scoping (see Credentials and Secrets).

Build strategies, tags and noise

By default a newly discovered branch is built once, and then a build starts when its head commit changes. Build strategies (provided by a plugin) refine this. For example, you can:

  • build tags only if they are newer than a given age, so the first scan does not build every old tag;
  • build change requests, branches or tags selectively instead of everything the scan finds.

For pull requests from unknown sources, some teams require a comment such as "build this please" before Jenkins runs the code, if their branch source plugin supports it.

Prefer a strategy that does not start a build at all over one that starts it and then does nothing.

Orphaned items

When a branch is merged and deleted, its Jenkins job becomes orphaned: it exists in Jenkins but no longer in the repository. The orphaned item strategy decides what happens. Typical settings keep the job for some days and a small number of builds, then delete it. Without this, a busy project would collect thousands of dead jobs, and JENKINS_HOME would fill up with their history (see Artifacts, Stash and Fingerprints for build retention).

A stand-in branch scanner

The code below imitates what a scan does. A fake repository lists branches, pull requests and tags; each may or may not contain a Jenkinsfile. The scanner applies discovery rules, builds the set of jobs, and compares it with the jobs that already exist so you can see what is created, kept and orphaned. The data is invented for the example.

JS A stand-in multibranch scan

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The branch without a Jenkinsfile and wip/old-idea (excluded by the name filter) are ignored, the fork pull request is skipped, and the three old items that no longer exist are reported as orphaned and would be removed after the retention period.

Building what was found

Next, a runner builds each discovered job with the stages that fit its kind. It applies the same when logic as the Jenkinsfile above, expressed as a small function. This is a model of the conditions, not the real evaluator.

JS A stand-in per-branch build plan

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Each kind of build gets a different pipeline from the same Jenkinsfile: main publishes, the pull request gets a preview, and the tag releases.

Indexing needs the repository to be reachable and the credentials to be valid. If a branch is missing, open the scan log first: it lists every branch it looked at and why it was accepted or skipped.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a multibranch pipeline create for each discovered branch?

    Each branch with a Jenkinsfile gets its own pipeline job, so changes to the Jenkinsfile in a branch affect only that branch.
  2. 2. In a multibranch build, which variable holds the pull request number?

    CHANGE_ID is set for pull request builds. CHANGE_TARGET holds the branch it will merge into.
  3. 3. Why is a trust policy important for pull requests from forks?

    Untrusted changes should not be able to run arbitrary code with your credentials. The trust policy limits that risk.
  4. 4. What is an orphaned item?

    When the source branch is deleted, the Jenkins job remains until the orphaned item strategy removes it.

Summary

  • A multibranch job scans a repository and creates a child pipeline for each branch, pull request or tag that has a Jenkinsfile.
  • Behaviors control what is discovered; trust policies protect you from unsafe pull requests.
  • Variables such as BRANCH_NAME, CHANGE_ID, CHANGE_TARGET and TAG_NAME let one Jenkinsfile behave differently per kind of build.
  • Organization folders apply the idea to every repository in an account or group.
  • Build strategies reduce unwanted builds, and the orphaned item strategy removes jobs for deleted branches.

Next, turn code into build output in Building Java, Node and Python Projects.