Multibranch Pipelines, Branch Sources, Pull Request Discovery, Jenkinsfile Trust, and Branch Indexing: Concepts, Architecture, and Mental Model

1. The problem Multibranch solves—and creates

A single Pipeline job can point at one Jenkinsfile and one branch. Real repositories change continuously: branches appear, pull requests open, branches disappear, and each head may carry a different Jenkinsfile. A Multibranch Pipeline turns repository discovery into Jenkins item lifecycle. Jenkins scans a configured branch source, creates a child job for each eligible head, then each child builds an exact revision.

The automation is powerful because developers do not need an administrator to create a job for every branch. The same automation is dangerous if “discovered code” is silently treated as “trusted control code.” A contributor who can edit a Jenkinsfile can ask Jenkins to run arbitrary Pipeline steps. Therefore discovery, trust, credentials, agent privilege and deployment must remain separate layers.

2. Mental model: discovery is not execution

Read this chain from left to right. Each arrow changes a different state:

flowchart TD
A[Branch-source configuration] --> B[Repository heads / change requests]
B --> C[Branch indexing decision]
C --> D[Candidate revision + trusted revision]
D --> E[Jenkinsfile selected for child job]
E --> F[Per-branch child job]
F --> G[Queue + agent/workspace]
G --> H[Build exact source revision]
H --> I[Status / reports / artifacts]
I --> J[Retention or orphaned-item policy]

Branch-source configuration defines the repository and discovery traits. Indexing asks the SCM source which heads exist. A head might be a normal branch or, with a provider plugin, a pull/change request. The candidate revision is the proposed code. A provider trust policy may separately choose a trusted revision for sensitive control files such as the Jenkinsfile. Jenkins then creates/updates a child job, whose build enters the normal queue/agent/workspace lifecycle from earlier chapters.

3. State inventory before changing anything

4. What branch indexing actually does

When you save a Multibranch project Jenkins performs an initial scan. The Branch API and provider source enumerate eligible heads and revisions. Jenkins creates child jobs for newly discovered heads that satisfy the Jenkinsfile criteria and updates existing children. A scan can also recognize removed branches and hand them to the orphaned-item strategy.

Indexing is controller/item state. It is not a queued build, not an executor allocation, and not proof that a Jenkinsfile completed. Preserve the scan log and any event-routing log before rescanning when discovery looks wrong.

5. Jenkinsfile trust: candidate code is not automatically control-plane code

Provider branch-source plugins can model pull requests and forks. The key security question is: may the contributor control the Jenkinsfile that decides which credentials, agents and deployment steps run? For untrusted forks, a provider trust strategy can require Jenkins to obtain trusted files from the target/origin revision instead of accepting a fork-modified Jenkinsfile. The exact options depend on the provider plugin.

6. Discovery credentials and build credentials are different

An SCM credential may allow Jenkins to list branches or clone a private repository. That does not justify giving the same child build a registry, signing, cloud or production credential. Discovery credentials should have the narrowest repository read scope possible. Protected deployment credentials should be available only to trusted control paths and identities.

Masking from Chapters 15–16 is not enough: malicious Pipeline code can transform or exfiltrate a value. The robust control is to make protected secrets unavailable to untrusted code in the first place.

7. Read-only inspection first

Before editing a Multibranch configuration, capture:

• parent item full name and configured branch source/provider;
• current Branch API / SCM API / provider plugin versions;
• Jenkinsfile path and discovery traits;
• latest indexing log/cause and discovered child jobs;
• for one child build: BRANCH_NAME, optional CHANGE_ID, build number/URL and exact Git SHA;
• orphaned-item retention policy and protected credential/agent boundaries.

Do not dump the complete environment: it may contain sensitive values. Record only the non-secret identities needed for attribution.

8. Orphaned items preserve or remove history by policy

When a branch disappears, Jenkins must decide what to do with its child job and builds. Immediate deletion saves disk but destroys evidence. Unlimited retention preserves evidence but grows controller state indefinitely. Choose a bounded policy based on audit, rollback and troubleshooting needs, and document it as controller configuration.

9. Common misconceptions

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog — chapter baseline Jenkins 2.568.3 LTS, released 2026-09-02 and tested with Java 21 and 25; labs use Java 21.
• Jenkins: Branches and Pull Requests — Multibranch discovery, branch child jobs, indexing and change-request environment variables.
• Pipeline: Multibranch — version 841.vec5b_9e1806ec, requiring Jenkins 2.504.3.
• Branch API — version 2.1280.v0d4e5b_b_460ef; documents Multibranch event/indexing log locations and routing.
• SCM API — version 728.vc30dcf7a_0df5.
• Git plugin — version 5.10.1.
• Git Client plugin — version 6.6.1; current releases include fixes for earlier command-injection issues on agents.
• GitHub Branch Source — provider-specific optional reference, version 1983.vfa_27ed961853, requiring Jenkins 2.541.1.
• Pipeline: Multibranch step/reference — documents provider pull-request trust strategies and trusted-file behavior.
• Credentials API — version 1511.v2e3cb_0008ef0; credentials remain a separate authorization boundary from SCM discovery.

Version note — 2026-09-17: executable local examples assume Jenkins 2.568.3 LTS, Java 21, Pipeline: Multibranch 841.vec5b_9e1806ec, Branch API 2.1280.v0d4e5b_b_460ef, SCM API 728.vc30dcf7a_0df5, Git 5.10.1, and Git Client 6.6.1. GitHub Branch Source 1983.vfa_27ed961853 is used only to explain a real provider fork/PR trust model; the mandatory local lab does not require an external SCM account or real SCM credential. Re-check provider plugin advisories and trust semantics before production adoption.