Multibranch Pipelines, Branch Sources, Pull Request Discovery, Jenkinsfile Trust, and Branch Indexing: Configuration, Design Choices, and Tradeoffs

1. One Pipeline job versus Multibranch

Multibranch is not “more modern” by default. Choose it when automatic SCM-head lifecycle is valuable enough to justify the additional discovery and trust surface.

2. Branch versus pull-request discovery

Normal branches are heads in the origin repository. Pull/change requests are provider concepts with additional identities: request number, source/fork repository, candidate revision, target branch and contributor relationship. Provider branch-source plugins expose traits that select which categories to discover and, crucially, how forked contributions are trusted.

Every extra discovery trait increases child-job cardinality. Combine this with Chapter 21: repository count × branches × PR heads × matrix cells can multiply queue demand rapidly.

3. Fork trust is a control-plane decision

A safe provider design answers three questions outside contributor-editable Pipeline code:

1. Which contributors/PR origins are trusted to supply control files?
2. Which revision supplies the Jenkinsfile or other trusted configuration?
3. Which credentials/agents/deployment capabilities are reachable from each trust class?

If the only guard is an if (env.CHANGE_ID) inside the same untrusted Jenkinsfile, a malicious contributor can delete the guard. Treat provider trust policy, job authorization, agent isolation and credential scope as the enforcement layer.

4. Periodic scans versus webhooks/events

A periodic scan is simple and resilient to missed events but consumes SCM/API capacity and introduces detection latency. Webhooks/events reduce latency but require authenticated provider integration and event routing. Many installations use provider events with a low-frequency safety scan.

5. Trusted libraries versus untrusted Jenkinsfile code

Shared Libraries become Chapter 24’s full topic, but Multibranch trust already depends on them. A library marked trusted can execute privileged APIs that sandboxed/untrusted Pipeline code cannot. Therefore:

• keep trusted-library repository write access narrow;
• prefer reviewed, immutable or version-controlled refs for privileged behavior;
• expose small intent-oriented functions rather than a generic “run arbitrary Groovy” surface;
• do not let untrusted code select an arbitrary privileged library revision.

6. Orphaned-item retention

Branch churn creates controller state. Immediate deletion reduces disk usage but weakens incident/audit history. Unlimited retention can grow JENKINS_HOME substantially. Choose a bounded strategy using branch lifetime, compliance, rollback needs and backup capacity. Document whether retention is based on days, item count, build count, or a combination supported by the configured strategy.

7. Credential and status-feedback design

SCM discovery usually needs repository metadata/read access; status feedback may need commit-status permissions; protected deployment needs unrelated privileges. Split these identities. A GitHub App or provider integration can be a good production pattern when narrowly scoped, but it remains provider-specific and must not become a broad organization credential merely for convenience.

8. Worked decision: public repository with external contributors

9. Rollback and reversibility

Changing discovery traits or trust strategy can add/remove many child jobs. Before editing, export/configure-as-code the parent item where available, record the current traits and orphaned policy, and preserve recent indexing logs. Roll back the smallest configuration change rather than deleting/recreating the Multibranch project.

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.