Source Control Integration, Git Plugin, Credentials, Polling, Webhooks, and Multirepository Checkout: Concepts, Architecture, and Mental Model

1. The problem: a branch name is not enough evidence

Jenkins often begins useful automation by fetching source code. That makes source-control integration look simple: type a repository URL, choose a branch, and run a build. In production, however, the important questions are more precise. Which repository was contacted? Which credential was allowed to contact it? Which refspec was fetched? Which immutable commit ended up in the workspace? Why did Jenkins decide to build at that moment? Did a second repository use the same trust boundary or a different one?

If those answers are missing, a green build is hard to reproduce. A mutable branch such as main may point to a different commit minutes later. A webhook may arrive twice. A broad credential may silently give an untrusted job access to repositories it does not need. A second checkout may overwrite the first workspace. The goal of this chapter is to make the source-to-workspace evidence chain explicit.

2. SCM integration as a causal chain

A Jenkins item stores SCM configuration or reads it from a Jenkinsfile. A manual action, timer, polling cycle, or webhook-related notification gives Jenkins a reason to inspect source. The Git plugin and Git Client plugin resolve the repository and refspec, perform fetch/checkout operations, and place source in an agent workspace. Jenkins can then calculate changelog metadata and expose checkout-related variables or returned values. Downstream build steps operate on that workspace state.

flowchart TD
 A[Repository URL + branch/refspec + credential ID] --> B[Manual / poll / webhook-related cause]
 B --> C[Git plugin SCM configuration]
 C --> D[Git Client implementation + network trust]
 D --> E[Fetch refs and resolve revision]
 E --> F[Exact commit SHA checked out]
 F --> G[Agent workspace]
 G --> H[Changelog + build metadata]
 G --> I[Build / test / package steps]
 H --> J[Evidence packet: repo + SHA + cause + tool versions]

The arrows prevent common category errors. A webhook does not directly prove which commit was built; it only causes Jenkins to evaluate repository state. A successful git fetch does not prove the intended branch was checked out. A branch label displayed in the UI is not immutable evidence. The workspace commit, build metadata, and repository identity must agree.

3. Core SCM objects and the state they own

4. Jenkins Git plugin and Git Client plugin are different layers

The Git plugin provides Jenkins SCM behavior: repository configuration, polling, checkout options, changelog integration, environment variables, and Pipeline SCM capabilities. The Git Client plugin provides the lower-level Git client API used by Git-aware Jenkins plugins. Its default implementation uses command-line Git, so agents performing checkout need an appropriate Git installation unless an alternative implementation is intentionally configured.

For this chapter's verified baseline, the Git plugin is 5.10.1 and Git Client plugin is 6.6.1. Record both because changing either can affect checkout behavior. Also record the actual git --version on each agent used by a lab; the course does not pretend that every environment ships the same Git binary.

# Read-only evidence on the disposable build agent.
git --version
git config --show-origin --get-regexp '^(user\.|credential\.|http\.|url\.)' || true
pwd

# After checkout:
git remote -v
git status --short --branch
git rev-parse HEAD
git show -s --format='%H %cI %s' HEAD

5. Credential type follows transport and scope follows trust

For HTTP or HTTPS repository access, the Git plugin expects a username/password-style credential, where a token can be supplied as the password component when the provider uses token authentication. For SSH repository access, it expects an SSH private-key credential. The job stores a credential ID; the secret itself remains in Jenkins' credential store.

Scope matters. A credential available to every job on a controller gives a larger attack surface than one limited to a folder or dedicated trust domain. A checkout of public synthetic source needs no credential at all. Start with that zero-secret case, then add the narrowest credential only when repository access genuinely requires it.

6. SSH host-key verification is part of source identity

An SSH private key proves the client may authenticate to a server; host-key verification helps prove the server is the intended server. Current Git Client plugin options include Known hosts file, Accept first connection, and Manually provided keys. The plugin also exposes a No verification mode, but its own documentation warns that this removes protection against man-in-the-middle attacks.

Use a strategy that fits the environment. Centrally managed fleets often prefer a controlled known_hosts file or manually managed keys. Small disposable environments can use accept-first where compatible, but administrators must understand that the first observed key becomes trusted state.

7. Polling and webhook notifications answer different questions

SCM polling asks, “Has repository state changed in a way that should trigger this job?” A webhook or Git plugin notifyCommit call says, “Repository activity occurred; evaluate the relevant job now.” In current Git plugin behavior, notifyCommit can trigger polling immediately for jobs configured with Poll SCM, even when no polling schedule is set. Jenkins still evaluates repository state before scheduling a build.

This distinction is valuable because it avoids treating untrusted webhook data as build truth. The Git plugin's current notifyCommit path uses an access token by default; this course keeps that protection enabled. The lab never recommends disabling the token mechanism just to make a curl command easier.

8. Multiple repositories require multiple identities

When one build consumes application source, infrastructure templates, and documentation from different repositories, record each repository independently. Do not save a single GIT_COMMIT value and assume it represents all source. Give each checkout a bounded directory and capture remote.origin.url plus HEAD from inside that directory.

for d in app infra docs; do
  if [ -d "$d/.git" ]; then
    printf '%s repo=%s sha=%s\n'       "$d"       "$(git -C "$d" remote get-url origin)"       "$(git -C "$d" rev-parse HEAD)"
  fi
done

A repository that supplies executable build scripts deserves more trust scrutiny than a repository consumed only as static input. “Second repository” is therefore not just a filesystem concern; it is an execution and credential boundary.

9. Read-only inspection before editing SCM configuration

Before changing a working Jenkins job, capture the current repository URL, branch specifier/refspec, credential ID (never its secret), Git/Git Client plugin versions, agent label, Git binary version, last build number/cause, exact checked-out SHA, changelog summary, workspace path, and any additional checkout identities. If an incident is active, preserve that evidence before retrying or rescanning.

The inspection goal is to answer: “What was configured?”, “What event/cause made Jenkins evaluate it?”, “What exact source was fetched?”, and “What exact bytes did downstream steps see?” Once those are clear, SCM changes become controlled rather than speculative.

10. DevOps connection: source evidence becomes build provenance

Jenkins does not create Git provenance automatically merely because a repository is configured. Reproducibility comes from correlating controller/plugin baseline, job identity, trigger cause, repository URL, resolved immutable SHA, credential scope, agent/toolchain, build number, and produced artifacts. That evidence is the bridge from “Jenkins built main” to a statement another engineer can independently verify.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS release and tested Java configurations.
• Git plugin — repositories, credentials, polling, push notifications, checkout behavior, environment variables, and plugin security notes.
• Git Client plugin — command-line/JGit implementations and SSH host-key verification strategies.
• scmGit Pipeline reference — explicit Git checkout configuration and supported checkout capabilities.
• Credentials security — limiting credential access and protecting secrets.
• Using credentials — credential kinds, stores, scope, and Jenkins usage.
• Controller Isolation — why routine checkout/build execution belongs on agents.
• Using a Jenkinsfile — Pipeline checkout and credential-handling patterns.