Multibranch Discovery and Checkout

Scenario: Manual branch jobs remain after branches disappear and a deployment runs from an ambiguous branch name.

One job definition, many jobs created automatically

A Multibranch Pipeline does something that looks like magic the first time you see it: point it at a repository, and it automatically creates a separate, running job for every branch (and often every pull request) that contains a Jenkinsfile - without you manually creating a single one of them.

Analogy: Think of a Multibranch Pipeline like a mailroom that automatically creates a new labeled mail slot the instant it notices a new department has been created in the company directory, and removes that slot once the department is dissolved. Nobody manually walks over to build a new slot every time; the mailroom just periodically checks the directory (this is called branch indexing) and reconciles what it finds. A slot for a department that shut down last month, but was never cleaned up, is exactly the kind of stale leftover that "orphan strategy" settings exist to control.

This automatic-discovery model is powerful for teams with many active feature branches and pull requests, but it also introduces its own vocabulary - indexing, discovery traits, orphaned jobs - that's worth understanding deliberately rather than treating as unexplained magic.

Pipeline example

pipeline { agent any; options { skipDefaultCheckout(true) }; stages { stage('SCM') { steps { checkout scm } } } }

Indexing manages branch jobs for you

A Multibranch Pipeline scans an SCM source, discovers branch heads (and optionally pull requests), and creates a child job for each one that actually contains a Jenkinsfile. Branch indexing is the act of discovering this configuration - it is not itself a build, even though it can trigger one for anything newly discovered. Webhooks provide low-latency notification the moment something changes; periodic scans exist to reconcile anything a missed webhook would otherwise leave stale, including branches that were deleted. Orphan strategy controls how long a child job for a now-deleted branch keeps its build history around, instead of either keeping it forever (wasting disk) or deleting it the instant the branch disappears (losing useful evidence too early).

Started branch indexing...
Checking branches...
    Checking branch main
      'Jenkinsfile' found
    Checking branch feature/login-fix
      'Jenkinsfile' found
    Checking branch old-experiment
      No Jenkinsfile found - skipping
Finished branch indexing. Duration: 2.1 sec

This is exactly what a scan looks like: each candidate branch is checked individually for a Jenkinsfile, and only branches that have one get a job created for them - "old-experiment" is simply skipped, not built and failed.

SCM traits shape what gets discovered at all

SCM traits configure branch discovery, tag discovery, pull-request discovery, and fork discovery, all independently. Pull requests specifically can build either the head revision alone (the contributor's code exactly as submitted) or a synthetic merge with the target branch. "Head" testing asks "does this contribution pass on its own?" while "merge" testing asks "does this contribution actually integrate cleanly with the current target?" - and a merge-tested result can go stale the moment the target branch moves again underneath it, even with zero new commits on the pull request itself. Enabling overlapping discovery strategies carelessly can cause the exact same revision to be built twice under two different discovered names.

Use the discovered SCM identity - don't reconstruct it

Inside a Multibranch job's Jenkinsfile, checkout scm uses the exact provider-specific revision that was selected during discovery - this is the safe, correct way to check out code in this context. Rebuilding a checkout URL yourself from BRANCH_NAME is unsafe, because a pull-request's display name (like PR-42) may not correspond to any real, directly-checkoutable remote branch at all. Record the commit SHA, change ID, merge target, trust strategy, and checkout mode actually used, since these determine exactly what got tested. Path filters and the configured Jenkinsfile path are themselves part of discovery policy and deserve the same review as any other pipeline configuration.

A pitfall: exposing production credentials to untrusted pull requests

Never expose release or deployment credentials to an untrusted fork's Jenkinsfile - remember from the previous module on architecture that a fork can freely rewrite its own Jenkinsfile to do anything, including exfiltrating whatever it can reach. Use a trusted Jenkinsfile definition (sourced from the target branch, not the fork) or route untrusted pull-request builds to an isolated, unprivileged job entirely, and reserve real publication and deployment steps for reviewed, post-merge revisions only. When an expected branch simply isn't showing up as a job, read the indexing log first: check API permissions, provider rate limits, the configured traits, any path filters, and whether a Jenkinsfile is actually present at the expected path - before jumping to manually creating a job that bypasses the whole designed discovery lifecycle (and will now need manual upkeep forever).

Goal: Practice the concrete behavior in jenkins-scm-trigger-recovery. Learn sections have no Jenkins terminal; the Jenkins lab opens the real shared service in a new full-screen tab inside your private folder.