Jenkins Configuration as Code, YAML Bundles, Secrets, Reloading, Validation, and Git-Managed Controller State: Concepts, Architecture, and Mental Model

1. The practical problem: UI configuration is easy to change and hard to reproduce

A Jenkins controller accumulates global settings: security realm, authorization, node defaults, clouds, tool configuration, credentials providers, system messages and plugin-specific settings. If those settings exist only as clicks in the UI, a second controller or disaster-recovery rebuild depends on memory, screenshots and undocumented ordering.

JCasC moves supported controller configuration into human-readable YAML that can be code-reviewed. That does not make all Jenkins state declarative. Plugins still have to be installed separately; jobs/build records remain separate; secrets require a protected source; some plugin data is not portable; and a running controller can drift after manual UI edits until configuration is reapplied.

2. Mental model: source → schema → apply → evidence → recovery

The causal chain is: versioned JCasC YAML plus secret references → installed plugin/configurator schema → validation → controller startup/reload → live runtime settings → export/drift evidence → Git rollback and, when needed, a JENKINS_HOME snapshot.

flowchart TD
A[Git commit: JCasC YAML] --> B[Secret references]
B --> C[Installed plugins + configurator schema]
C --> D[Parse / resolve / validate]
D --> E[Startup or administrative reload]
E --> F[Live controller configuration]
F --> G[Export + read-only inspection]
G --> H[Drift comparison]
H --> I[Revert commit / restore snapshot]
I --> D

YAML → schema: a key is meaningful only if Jenkins core or an installed plugin contributes the matching configurator. Secret reference → resolution: the placeholder is committed, but the value comes from a protected source at apply time. Validation → apply: YAML syntax success is not enough; JCasC must resolve configurators and types. Apply → live state: reload changes controller-global state without recreating builds/workspaces. Live state → evidence: export, logs and UI inspection are observations, not automatically the canonical source. Recovery: Git handles desired configuration; snapshots still protect controller data that JCasC does not own.

3. State that must remain distinct

Changing a JCasC system message does not alter a running agent workspace. Installing a new plugin is not a JCasC reload. Restoring YAML cannot recreate lost build history. Keep those boundaries explicit.

4. How JCasC finds configuration

The plugin reads CASC_JENKINS_CONFIG or the equivalent Java system property. A source may be a local file, directory, file URI, HTTP/HTTPS URL, or comma-separated set. If the source is a directory, JCasC recursively discovers YAML files.

5. Plugin installation is a prerequisite, not JCasC content

JCasC configures objects exposed by Jenkins core and installed plugins. It does not install those plugins. A reproducible controller therefore needs two versioned inputs: a plugin manifest/controller image and a JCasC repository. Upgrade the plugin set in a tested candidate first, validate the candidate schema against the YAML, then promote the pair.

If YAML refers to a plugin setting that is missing or renamed, the failure belongs to the controller/plugin/configurator layer—not the queue or agent layer.

6. Secret placeholders and strict resolution

JCasC supports SecretSource resolution. The source code should contain a placeholder such as ${lab_admin_password}, while the value is injected from a file-backed secret, external provider or other protected resolver. Environment variables can also resolve values, but they are broadly observable in many runtimes and are not the preferred home for long-lived secrets.

Enable CASC_STRICT_SECRET_RESOLUTION=true for governed environments. Without strict resolution, an unresolved variable can become an empty string with a warning; strict mode aborts the reload when a required secret is missing, leaving the prior working configuration in place.

7. Read-only inspection before mutation

Before any reload, record the controller and the exact source identity. Do not dump the whole container environment after secrets are injected.

# Safe host-side inspection of non-secret identities only
sha256sum jcasc/*.yaml
git rev-parse HEAD
docker image inspect jenkins/jenkins:2.568.3-lts-jdk21 \
  --format '{{json .RepoDigests}}'

# On the controller UI:
# Manage Jenkins → Plugins → Installed
# Manage Jenkins → Configuration as Code
# Record JCasC plugin version, configured source, and last-load evidence.

Also inspect the instance-specific JCasC reference/documentation. That reference is generated from the installed controller/plugin set, which is exactly why a YAML file must be tested against the target baseline rather than an abstract example.

8. Validation has layers

9. Reload is an administrative state change; restart is a runtime boundary

Current JCasC supports controlled reload from the UI, authenticated endpoint and Jenkins CLI. The reload action is privileged because it can change global security and controller behavior. Do not expose a reload token casually or call reload from a normal Pipeline; upstream documentation specifically discourages the Groovy/Pipeline shortcut.

Reload is appropriate when the installed configurators support the desired change and no plugin/core/Java lifecycle change is involved. Restart is the stronger boundary when plugins or runtime changed, when startup itself must be tested, or when the rollback plan depends on a clean initialization.

10. Export, drift and Git identity

The export feature is valuable evidence: it shows what the current controller can serialize. It is not automatically a clean replacement for the authored repository. Exports may include defaults, plugin-version-specific structure and encrypted values bound to the current controller secret key. Review and normalize rather than committing exports blindly.

Drift is the difference between approved source and live controller state. A manual UI edit to a JCasC-owned field can create temporary drift; a controlled reload/startup should reconcile it. Record both the drift observation and the Git commit that reasserted state.

11. Common wrong approaches

• Commit literal passwords/tokens into YAML because “the repository is private.”
• Use a mutable remote YAML URL with no commit/digest evidence.
• Assume JCasC installs missing plugins.
• Split the same attribute across files and expect last-file-wins.
• Treat “reload returned 200” as proof every job and external integration still works.
• Delete JENKINS_HOME when a YAML key fails instead of preserving the first error.
• Allow application developers to edit admin-equivalent configuration without protected review.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins — Configuration as Code — handbook overview and operating model.
• Configuration as Code plugin — current release, installation, CASC_JENKINS_CONFIG, supplementary-source rules and plugin prerequisites.
• JCasC upstream repository — canonical feature documentation, examples and compatibility notes.
• JCasC — Handling Secrets — SecretSource behavior, file/Docker/Kubernetes/Vault options and strict secret resolution.
• JCasC — Triggering Configuration Reload — UI, authenticated API and CLI reload paths and their privilege requirements.
• JCasC — JSON Schema — instance-specific schema support; current implementation remains beta and should not be the only validation gate.
• Credentials plugin — current credentials API baseline used by the disposable controller image.
• Jenkins LTS changelog and Java support policy — current core/runtime assumptions.