Jenkins / Execution and source foundations / Lesson 3

SCM checkout and multibranch identity

Connect the Jenkinsfile revision, checked-out application, branch context, and candidate evidence.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish branch discovery from a build of an immutable revision.
Review checkout behavior without contacting source control.

Discovery is not the same as validation

Multibranch Pipeline discovers branches or change requests according to configured SCM sources and plugins, creating appropriate job contexts for Jenkinsfiles. Discovery determines what can be considered; a run then evaluates particular source and configuration. Branch indexing success does not prove the application compiled or that a change request is trusted. Parcel’s record should distinguish repository source, branch or change-request identity, Jenkinsfile provenance, and actual checked-out revision. Plugin-specific trust strategies can affect which definition is used for untrusted changes and must be reviewed on the real installation.

A source context has a concrete meaning

In a suitable Pipeline-from-SCM or multibranch context, checkout scm uses the SCM configuration associated with the run. That is not a universal request for the newest default branch. Declarative commonly performs a default checkout when entering an appropriate agent context unless configured otherwise. If an author also checks out manually, duplicate or inconsistent source operations can result. Decide which layer owns checkout and preserve the resolved revision. The illustration below makes that ownership explicit while relying on an existing valid SCM context.

groovy An explicit checkout ownership illustration

pipeline {
    agent { label "parcel-lab" }
    options { skipDefaultCheckout(true) }
    stages {
        stage("Source") {
            steps { checkout scm }
        }
    }
}

The synthetic label, SCM configuration, repository, plugin support, and access would have to exist in an authorized lab. No fetch, checkout, repository connection, or Jenkins run occurs here.

A change head and a merge result differ

A change-request source may be tested alone or combined with a target depending on SCM source configuration and supported discovery strategies. Those are different evidence claims. If the target advances, a previously tested combination can become stale while the proposal head remains unchanged. Do not infer exact behavior from BRANCH_NAME alone or assume every plugin creates the same synthetic merge. Record source and tested-combination identities and define when revalidation is required. Friendly labels are navigation aids, not a complete description of the tested tree.

Match evidence to the intended revision

The complete local model below checks whether every required observation names the candidate’s source revision. It rejects a unit result from a different revision even if its status says success. Labels such as lab-r4 are synthetic and are not Git hashes. A real system needs authenticated producer records and immutable content identity, not a contributor-provided assertion. The model intentionally omits SCM protocol, merge computation, and plugin behavior. It makes the source-evidence relationship visible without contacting any remote repository.

python Reject evidence for another source revision

candidate_revision = "lab-r4"
evidence = {"compile": {"revision": "lab-r4", "ok": True}, "unit": {"revision": "lab-r3", "ok": True}}
ready = all(v["ok"] and v["revision"] == candidate_revision for v in evidence.values())
print(ready)
print(sorted(k for k, v in evidence.items() if v["revision"] != candidate_revision))

Expected output

False
['unit']

The program evaluates synthetic dictionaries only. A real gate also needs the declared required check set; this example isolates revision matching rather than demonstrating a complete release predicate.

SCM access does not authorize source execution

Read access to a repository lets the job obtain bytes; it does not make every branch or fork safe to execute with credentials. Review who can modify the Jenkinsfile, build scripts, dependency hooks, and shared-library references. A trusted Jenkinsfile can still execute untrusted application code through a normal build command. Separate restricted proposal validation from privileged candidate promotion, and keep secrets out of diagnostic revision records. This boundary remains necessary even when the checkout plugin correctly verifies the requested revision.

Common errors and fixes

Branch indexing is reported as a passed application build.

Why it happens: Discovery evidence was stretched into execution evidence.
How to fix it: Inspect the actual run and required test outcomes.
Prevent it next time: Keep discovery, checkout, and validation statuses distinct.

Manual checkout and automatic checkout resolve conflicting inputs.

Why it happens: Source ownership was not defined at the Pipeline level.
How to fix it: Choose a deliberate checkout path and retain its resolved identity.
Prevent it next time: Review default checkout settings when adding manual SCM steps.

A successful status from an older revision satisfies a new candidate.

Why it happens: Evidence is selected by name rather than source relationship.
How to fix it: Require the intended immutable revision for each mandatory observation.
Prevent it next time: Retain source and tested-combination identities with artifacts.

Check your understanding

1. The proposal head is unchanged but its target advanced. Must the previous combined-state result remain sufficient?

Show worked solution

No. The intended integration state may have changed. Apply the repository’s supported revalidation policy and record which combination was actually tested. Source-head evidence and combined-tree evidence answer different questions.

2. Why is checkout scm not described as checking out latest main?