Lesson 010 · Jenkins Learning Path

Configure Jenkins with JCasC and Reproducible Bootstrap

Anil Jalela · Published Sep 5, 2026 · 5 min read

Jenkins Configuration as Code turns controller settings into reviewable YAML, but it does not automatically capture every plugin, job, credential secret or host dependency. A reproducible controller needs a versioned plugin set, external secret injection and a tested bootstrap order.

Start from a known controller checkpoint

Use the accepted controller and agent checkpoint from the prior lesson. Record the Jenkins version, Java runtime, active configuration, plugin inventory and current Git revision before changing this boundary.

java -version
sudo systemctl is-active jenkins
sudo journalctl -u jenkins -n 50 --no-pager
curl -fsS http://127.0.0.1:8080/login >/dev/null

Understand the operating boundary

Prepare the lab

Install the Configuration as Code plugin on a disposable controller, view the current export and remove generated secrets or environment-specific values before committing anything.

sudo install -d -o jenkins -g jenkins -m 0750 /etc/jenkins/casc
sudo install -m 0640 -o jenkins -g jenkins /dev/null /etc/jenkins/casc/jenkins.yaml
sudo systemctl edit jenkins
# add Environment="CASC_JENKINS_CONFIG=/etc/jenkins/casc/jenkins.yaml"
sudo systemctl daemon-reload

Implement it step by step

1. Record the exact core and plugin versions that understand the exported attributes.
2. Split YAML by ownership only when all files form one unambiguous configuration.
3. Reference secrets through environment or supported secret sources; never export encrypted controller values into Git.
4. Use the JCasC check endpoint or UI validation before reload.
5. Provision jobs through reviewed job definitions or organization discovery rather than undocumented clicks.
6. Rebuild a clean lab controller and compare effective configuration before production use.

The export is a starting observation, not automatically a portable desired state. Plugin-specific sections disappear when their plugin is absent and can become invalid when attributes change. The plugin catalog and JCasC revision therefore form one release unit.

jenkins:
  systemMessage: 'Managed by JCasC'
  numExecutors: 0
  mode: EXCLUSIVE
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: admin-lab
          password: "${ADMIN_LAB_PASSWORD}"
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false
unclassified:
  location:
    url: 'https://jenkins.example.test/'

Bootstrap order is operationally significant. Install the supported core and the pinned plugin catalog before loading attributes owned by those plugins. Make secret sources available before interpolation, but restrict their files or workload identity to the controller process. Load JCasC, provision discoverable jobs, connect agents and only then admit production triggers. A controller that starts with half its policy missing is not ready merely because the login page responds.

Detect drift by comparing the effective export with reviewed source, while filtering values that are generated or intentionally external. Decide whether emergency UI changes are prohibited or allowed temporarily. If allowed, require an incident record and a follow-up source commit; otherwise the next reload silently removes the repair.

Verify the positive path

Run validation with the same plugin set that will load the file. Reload on the disposable controller, inspect system message, executor count, URL and authorization, then restart to prove bootstrap persistence.

sudo systemctl restart jenkins
sudo journalctl -u jenkins -n 200 --no-pager
curl -fsS https://jenkins.example.test/login >/dev/null
git -C /srv/jenkins-casc rev-parse HEAD
sha256sum /etc/jenkins/casc/jenkins.yaml

Reject a plugin-owned unknown attribute

Add a misspelled or removed attribute in the lab. Validation must fail before production reload. Retain the error showing its path, restore the prior Git revision and prove that a restart loads the accepted configuration.

cp /etc/jenkins/casc/jenkins.yaml /tmp/jenkins.yaml.bad
printf '\n  unknownAttribute: true\n' >> /tmp/jenkins.yaml.bad
# Submit only to the lab JCasC validation endpoint or UI
git -C /srv/jenkins-casc diff --exit-code

Troubleshoot by failed layer

Unsafe shortcuts

• Unsafe: granting administrator access to avoid designing a narrow permission removes accountability.
• Unsafe: binding protected secrets around untrusted repository code permits exfiltration despite masking.
• Unsafe: changing controller state without a verified backup and rollback turns a small error into an outage.

Operate, recover and retain evidence

Own the configuration, plugin and credential dependencies explicitly. Record the controller version, Git revision, immutable tool or artifact identity, initiator, approver and acceptance result. Rehearse the failure path on a disposable controller before adopting it as production procedure.

sudo systemctl stop jenkins
sudo rsync -aHAX --numeric-ids /backup/jenkins-known-good/ /var/lib/jenkins/
sudo restorecon -RF /var/lib/jenkins 2>/dev/null || true
sudo systemctl start jenkins
sudo journalctl -u jenkins -n 150 --no-pager

Worked use cases

Knowledge checks

What are the main JCasC sections?

jenkins, tool, unclassified and credentials are common top-level areas.

Is an export safe to commit unchanged?

No; inspect it for secrets and generated or environment-specific data.

Can JCasC replace a backup?

No; build history, secrets, keys and other state still require protected backup.

Why keep controller configuration in source?

It provides review, attribution and repeatable recovery.

Why record the exact Jenkins version?

Core and plugin behavior depends on the running baseline.

Does a successful process prove service acceptance?

No; verify the user-facing or downstream result.

Why test one negative case?

It proves the control rejects an invalid or unauthorized path.

Why use a disposable rehearsal?

Controller changes can prevent the same interface from repairing itself.

Independent lab

1. Capture the starting version, configuration and plugin evidence.
2. Implement the change on a disposable controller or folder.
3. Run one successful case and one controlled failure.
4. Restore the accepted state and prove service behavior, not only process state.
5. Repeat from a clean source checkout without relying on remembered UI actions.

Official references

• Jenkins Configuration as Code
• JCasC plugin documentation
• Jenkins plugin management