Jenkins Configuration as Code
Define a whole Jenkins controller in Git: JCasC YAML for settings and credentials, Job DSL for jobs, plugins.txt for plugins, and a tested way to rebuild it.
By The Dark DebuggerUpdated 28 min read
This article turns a hand-configured Jenkins into files in a Git repository: the
Configuration as Code plugin (JCasC) for system settings, security and credentials, Job
DSL for jobs, and plugins.txt for plugins. By the end you will have started a complete
controller from those files, changed it with a reload, broken it on purpose, and validated
a change before applying it. It builds on
Installing Jenkins,
Credentials and Secrets and
Agents and Distributed Builds; the
multibranch job created here is explained properly in
Multibranch Pipelines and Webhooks.
Everything in this article ran on a throwaway controller on port 8093, started from the
WAR file, with its own JENKINS_HOME. Never experiment with configuration reloads on a
controller other people depend on.
Why click-ops does not scale
Picture the disk under a team's Jenkins controller failing on a Monday. The backup restores the jobs, but it is three weeks old, and nobody can say which of the forty settings under Manage Jenkins changed since: the security realm, the matrix permissions, the agent definitions, the build discarder, the mail server, the credentials someone added for a new registry. The same problem shows up without a disaster: the staging controller drifts from production, nobody can review a permission change before it happens, and "who turned off CSRF protection?" has no answer.
Configuration as code fixes this by making the controller reproducible from three kinds of files:
| What | File | Tool |
|---|---|---|
| Which Jenkins and plugins | plugins.txt (plus a pinned WAR or image tag) | Plugin Installation Manager |
| How Jenkins is configured | jenkins.yaml | Configuration as Code plugin |
| Which jobs exist | Job DSL scripts | Job DSL plugin |
| Secrets | environment variables or files, never Git | JCasC variable substitution |
The controller's disk then only holds things you cannot regenerate: build history and the encryption keys.
Start from an export
You do not have to learn the YAML schema from documentation. Configure something, export it, and copy the parts you need. A minimal configuration file to start a controller with:
jenkins:
systemMessage: "Throwaway controller, configured by JCasC"
securityRealm:
local:
allowsSignup: false
users:
- id: "admin"
password: "${JENKINS_ADMIN_PASSWORD}"
authorizationStrategy: loggedInUsersCanDoAnythingJCasC finds its configuration through the CASC_JENKINS_CONFIG environment variable,
which may point to a file, a directory (every .yaml file in it is loaded) or a URL.
This script starts a controller with the configuration in ./casc and secrets from
./secrets.env:
#!/usr/bin/env bash
# start-controller.sh: start a throwaway controller whose configuration lives in ./casc
set -euo pipefail
cd "$(dirname "$0")"
export JENKINS_HOME=$PWD/home
export CASC_JENKINS_CONFIG=$PWD/casc
set -a; source ./secrets.env; set +a
nohup java -Xmx512m \
-Djenkins.install.runSetupWizard=false \
-Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true \
-jar /opt/jenkins/jenkins.war \
--httpPort=8093 --httpListenAddress=127.0.0.1 > jenkins.log 2>&1 &
echo $! > jenkins.pid
echo "started controller (pid $(cat jenkins.pid)), log in $PWD/jenkins.log"-Djenkins.install.runSetupWizard=false skips the setup wizard, which is safe here only
because the YAML creates an admin user and a security realm. ALLOW_LOCAL_CHECKOUT is
needed later because the example jobs check out Git repositories from the local disk.
set -a exports every variable that secrets.env defines, so Jenkins inherits them.
The plugins directory came from an existing controller, copied with hard links
(cp -al) so it took no extra disk space. We get to building it from plugins.txt below.
The first thing I tried after it started was the CLI:
export JENKINS_URL=http://localhost:8093/ JENKINS_USER_ID=admin JENKINS_API_TOKEN=Adm1n-Casc-Lab-2026
java -jar jenkins-cli.jar who-am-iCLI handshake failed with status code 403
Content-Length: 0
[…]
Server: Jetty(12.1.14)
Vary: Accept-Encoding
X-CLI-Error: Jenkins URL is not configured (set Jenkins URL in the configuration)
X-Content-Type-Options: nosniffThe setup wizard normally asks for the Jenkins URL, and I skipped it. The CLI's default
WebSocket mode refuses to work without it (java -jar jenkins-cli.jar -http who-am-i
still worked). The fix belongs in the YAML, under unclassified:
unclassified:
location:
url: "http://localhost:8093/"After adding that to casc/jenkins.yaml, I reloaded the configuration over HTTP. With a
password (rather than an API token) Jenkins requires a CSRF crumb for POST requests:
CRUMB=$(curl -s -c cookies.txt -u "$JENKINS_USER_ID:$JENKINS_API_TOKEN" "${JENKINS_URL}crumbIssuer/api/json" | jq -r '.crumbRequestField + ":" + .crumb')
curl -s -o /dev/null -w "reload: HTTP %{http_code}\n" -b cookies.txt -u "$JENKINS_USER_ID:$JENKINS_API_TOKEN" -H "$CRUMB" -X POST "${JENKINS_URL}configuration-as-code/reload"
java -jar jenkins-cli.jar who-am-i
java -jar jenkins-cli.jar export-configuration > exported.yaml
wc -l exported.yamlreload: HTTP 302
Authenticated as: admin
Authorities:
authenticated
FACTOR_PASSWORD
224 exported.yamlTwo lines of configuration became a 224-line export, because the export includes every default. An excerpt:
configuration-as-code:
deprecated: "reject"
restricted: "reject"
unknown: "reject"
version: "1"
[…]
jenkins:
authorizationStrategy: "loggedInUsersCanDoAnything"
crumbIssuer: "standard"
disableRememberMe: false
labelAtoms:
- name: "built-in"
[…]
numExecutors: 2
[…]
slaveAgentPort: 0
systemMessage: "Throwaway controller, configured by JCasC"
[…]
unclassified:
[…]
location:
adminAddress: "address not configured yet <nobody@nowhere>"
url: "http://localhost:8093/"
[…]
timestamper:
allPipelines: false
elapsedTimeFormat: "'<b>'HH:mm:ss.S'</b> '"
systemTimeFormat: "'<b>'HH:mm:ss'</b> '"Use the export as a dictionary, not as your configuration. Find the setting you changed in
the UI, copy that block into your own file, and leave the defaults out. A short file that
only states decisions is something people can review. unknown: "reject" at the top is
also worth knowing: JCasC refuses keys it does not recognise, which is what makes typos
loud (see Common mistakes). The CLI has two more JCasC commands, reload-jcasc-configuration
and check-configuration, alongside export-configuration.
The structure of a configuration
A JCasC file has a small number of root keys. Each maps to a part of Manage Jenkins:
| Root key | Covers | UI equivalent |
|---|---|---|
jenkins | core settings: executors, security realm, authorization, nodes, clouds, views | System, Security, Nodes |
credentials | the global credential store | Credentials |
unclassified | settings contributed by plugins: Jenkins URL, timestamper, mailer, build discarders, shared libraries | System (most of the page) |
tool | tool installations: Git, JDK, Maven | Tools |
security | security settings from plugins, such as Job DSL script security | Security |
jobs | Job DSL scripts to run (added by the Job DSL plugin) | none: this replaces creating jobs by hand |
I split the payments team's controller into three files in one directory, which
CASC_JENKINS_CONFIG loads together:
tree casccasc
├── credentials.yaml
├── jenkins.yaml
└── jobs.yaml
1 directory, 3 filesjenkins.yaml: core, security, nodes, plugin settings
jenkins:
systemMessage: "payments CI. Managed by JCasC: changes made in the UI are overwritten on the next reload."
numExecutors: ${BUILTIN_EXECUTORS:-0}
quietPeriod: 0
securityRealm:
local:
allowsSignup: false
users:
- id: "admin"
password: "${JENKINS_ADMIN_PASSWORD}"
- id: "dev"
password: "${JENKINS_DEV_PASSWORD}"
authorizationStrategy:
globalMatrix:
entries:
- user:
name: "admin"
permissions:
- "Overall/Administer"
- user:
name: "dev"
permissions:
- "Overall/Read"
- "Job/Read"
- "Job/Build"
nodes:
- permanent:
name: "linux-agent-1"
remoteFS: "/home/sid/controller/agent-1"
numExecutors: 2
labelString: "ubuntu-24 jdk21 maven"
retentionStrategy: "always"
launcher:
inbound:
webSocket: true
unclassified:
location:
url: "http://localhost:8093/"
adminAddress: "Payments CI <ci-admin@example.com>"
timestamper:
allPipelines: true
buildDiscarders:
configuredBuildDiscarders:
- "jobBuildDiscarder"
- simpleBuildDiscarder:
discarder:
logRotator:
numToKeepStr: "30"
tool:
git:
installations:
- name: "Default"
home: "git"Reading it top to bottom:
numExecutors: ${BUILTIN_EXECUTORS:-0}means "the value ofBUILTIN_EXECUTORS, or 0 if it is not set". Production leaves it unset, so the controller runs no builds (the reasons are in Agents and Distributed Builds). My lab sets it to 1 for the parts of this article that need to run a job without starting an agent.securityRealm.localcreates two users with passwords from the environment. In a company you would configure LDAP or SAML here instead, also through JCasC.globalMatrix(from the Matrix Authorization Strategy plugin) givesadmineverything anddevread and build permission only.nodesdefines the agentlinux-agent-1, the same thing as Nodes → New Node in the UI. The agent process still has to be started on the agent machine.unclassifiedsets the Jenkins URL (the CLI needs it), turns on timestamps for every pipeline, and adds a global build discarder that keeps 30 builds per job.
credentials.yaml: secrets from the environment
credentials:
system:
domainCredentials:
- credentials:
- string:
scope: GLOBAL
id: "sonar-token"
description: "SonarQube analysis token"
secret: "${SONAR_TOKEN}"
- usernamePassword:
scope: GLOBAL
id: "registry"
description: "Container registry push account"
username: "ci-pusher"
password: "${REGISTRY_PASSWORD}"
- basicSSHUserPrivateKey:
scope: GLOBAL
id: "deploy-key"
description: "SSH key for the deploy user"
username: "deploy"
privateKeySource:
directEntry:
privateKey: "${readFile:${DEPLOY_KEY_FILE}}"
- file:
scope: GLOBAL
id: "staging-kubeconfig"
description: "kubeconfig for the staging cluster"
fileName: "kubeconfig"
secretBytes: "${readFileBase64:${KUBECONFIG_FILE}}"No secret is in this file. JCasC resolves the placeholders when it applies the configuration:
| Syntax | Resolves to |
|---|---|
${NAME} | environment variable (or system property) NAME |
${NAME:-default} | the same, with a fallback |
${readFile:/path} | the contents of a file |
${readFileBase64:/path} | a file's contents, Base64-encoded (what secretBytes expects) |
Placeholders can nest, as in ${readFile:${DEPLOY_KEY_FILE}}, where the variable holds a
path. Files work well with Kubernetes secrets and Docker secrets, which are mounted as
files. The environment for my lab came from secrets.env, which never goes into Git:
JENKINS_ADMIN_PASSWORD=Adm1n-Casc-Lab-2026
JENKINS_DEV_PASSWORD=Dev-Casc-Lab-2026
SONAR_TOKEN=squ_7d1e4f8a3c6b0d2e5f9c2e7a1b8d3f60e5a2c9b7
REGISTRY_PASSWORD=Wq8-tVz3-Kp2r-Ld9x
DEPLOY_KEY_FILE=/home/sid/creds/deploy_key
KUBECONFIG_FILE=/home/sid/creds/kubeconfigEnvironment variables are read once, when the Java process starts. A reload re-reads the
YAML and any readFile paths, but not new environment variables. If you rotate a secret
that comes from the environment, restart the controller; if you want rotation without a
restart, use readFile and update the file.
jobs.yaml: jobs through Job DSL
The jobs key runs Job DSL scripts when the configuration is applied. Job DSL is a Groovy
API that describes jobs the way JCasC describes settings:
jobs:
- script: |
folder('payments') {
description('Payments team pipelines. Created by Job DSL from JCasC.')
}
- script: |
multibranchPipelineJob('payments/payments-api') {
branchSources {
branchSource {
source {
git {
id('payments-api')
remote('file:///home/sid/repos/payments-api')
traits {
gitBranchDiscovery()
}
}
}
}
}
orphanedItemStrategy {
discardOldItems {
numToKeep(5)
}
}
}
- script: |
pipelineJob('payments/nightly-db-report') {
description('Nightly slow-query report')
properties {
pipelineTriggers {
triggers {
cron {
spec('H 2 * * *')
}
}
}
}
definition {
cps {
sandbox(true)
script('''
pipeline {
agent any
stages {
stage('Report') {
steps {
sh 'echo "slow query report for $(date +%F) on $NODE_NAME"'
}
}
}
}
'''.stripIndent())
}
}
}
- script: |
job('seed') {
description('Regenerates jobs from the ci-jobs repository')
scm {
git {
remote {
url('file:///home/sid/repos/ci-jobs')
}
branch('main')
}
}
steps {
jobDsl {
targets('jobs/**/*.groovy')
removedJobAction('DELETE')
removedViewAction('DELETE')
}
}
}This creates a folder, a multibranch pipeline that discovers every branch of the
payments-api repository, a nightly pipeline with an inline Jenkinsfile and a cron
trigger, and a freestyle seed job that we will use in a moment. Use | (a literal block)
for the scripts: with > YAML folds the lines together and the Groovy breaks.
Starting the controller from code
With an empty JENKINS_HOME (only the plugins directory) and the three files in
casc/:
./start-controller.shstarted controller (pid 17755), log in /home/sid/controller/jenkins.log
controller up after 14s(The second line is from a small loop that polls /login until it answers 200.) The log
shows Job DSL running during startup:
Processing provided DSL script
2026-11-10 06:23:58.708+0000 [id=47] INFO j.j.plugin.JenkinsJobManagement#createOrUpdateConfig: createOrUpdateConfig for payments
Processing provided DSL script
2026-11-10 06:24:00.029+0000 [id=47] INFO j.j.plugin.JenkinsJobManagement#createOrUpdateConfig: createOrUpdateConfig for payments/payments-api
Processing provided DSL script
2026-11-10 06:24:00.592+0000 [id=47] INFO j.j.plugin.JenkinsJobManagement#createOrUpdateConfig: createOrUpdateConfig for payments/nightly-db-report
Processing provided DSL script
2026-11-10 06:24:01.207+0000 [id=47] INFO j.j.plugin.JenkinsJobManagement#createOrUpdateConfig: createOrUpdateConfig for seed
2026-11-10 06:24:01.237+0000 [id=49] INFO jenkins.InitReactorRunner$1#onAttained: System config adapted
2026-11-10 06:24:01.238+0000 [id=51] INFO jenkins.InitReactorRunner$1#onAttained: Loaded all jobs
[…]
2026-11-10 06:24:01.834+0000 [id=38] INFO hudson.lifecycle.Lifecycle#onReady: Jenkins is fully up and runningNow let's check that the controller is what the files say, starting with the system message, the executors and the jobs:
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/api/json?tree=numExecutors,description,jobs%5Bname,jobs%5Bname%5D%5D" | jq .{
"_class": "hudson.model.Hudson",
"numExecutors": 0,
"description": "payments CI. Managed by JCasC: changes made in the UI are overwritten on the next reload.",
"jobs": [
{
"_class": "com.cloudbees.hudson.plugins.folder.Folder",
"name": "payments",
"jobs": [
{
"_class": "org.jenkinsci.plugins.workflow.job.WorkflowJob",
"name": "nightly-db-report"
},
{
"_class": "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject",
"name": "payments-api"
}
]
},
{
"_class": "hudson.model.FreeStyleProject",
"name": "seed"
}
]
}The credentials, the agent definition, and the dev user's limited permissions:
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/manage/credentials/store/system/domain/_/api/json?tree=credentials%5Bid,displayName%5D" |
jq -r '.credentials[] | "\(.id)\t\(.displayName)"'
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/computer/api/json?tree=computer%5BdisplayName,numExecutors,offline%5D" |
jq -c '.computer[]'
curl -s -u "dev:$JENKINS_DEV_PASSWORD" "http://localhost:8093/whoAmI/api/json" | jq -c '{name, authorities}'
curl -s -o /dev/null -w "dev -> /manage/ HTTP %{http_code}\n" -u "dev:$JENKINS_DEV_PASSWORD" "http://localhost:8093/manage/"sonar-token SonarQube analysis token
registry ci-pusher/****** (Container registry push account)
deploy-key deploy (SSH key for the deploy user)
staging-kubeconfig kubeconfig (kubeconfig for the staging cluster)
{"_class":"hudson.model.Hudson$MasterComputer","displayName":"Built-In Node","numExecutors":0,"offline":false}
{"_class":"hudson.slaves.SlaveComputer","displayName":"linux-agent-1","numExecutors":2,"offline":true}
{"_class":"hudson.model.Hudson","name":"dev","authorities":["authenticated","FACTOR_PASSWORD"]}
dev -> /manage/ HTTP 403The multibranch job had already scanned the repository and queued builds for both
branches. With zero executors and the agent not connected, every build waits, and the
timestamps show the timestamper setting in effect:
[2026-11-10T06:24:09.062Z] Started by user admin
[2026-11-10T06:24:09.132Z] [Pipeline] Start of Pipeline
[2026-11-10T06:24:09.426Z] [Pipeline] node
[2026-11-10T06:24:24.443Z] Still waiting to schedule task
[2026-11-10T06:24:24.444Z] Waiting for next available executorThat is the correct behaviour for a production controller; connecting linux-agent-1 is
the inbound-agent procedure from the agents article. For the rest of this section I
restarted the lab controller with BUILTIN_EXECUTORS=1 so jobs could run on the built-in
node without a second Java process. After the multibranch scan, both branch jobs had a
successful first build (blue):
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/job/payments/job/payments-api/api/json?tree=jobs%5Bname,color%5D" | jq -c '.jobs[]'{"_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"feature%2Frefund-api","color":"blue"}
{"_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"main","color":"blue"}Seed jobs: job definitions in their own repository
Putting every job in jobs.yaml works for a handful. Once a team owns its own jobs, the
usual pattern is a seed job: one job, defined in JCasC, that checks out a repository of
Job DSL scripts and runs them. Teams change their jobs by opening pull requests against
that repository, without touching the controller's configuration.
The ci-jobs repository holds one script, jobs/payments.groovy:
pipelineJob('payments/release-notes') {
description('Created by the seed job from ci-jobs/jobs/payments.groovy')
definition {
cps {
sandbox(true)
script('''\
pipeline {
agent any
stages {
stage('Notes') {
steps {
echo "Collecting release notes for payments-api on ${env.NODE_NAME}"
}
}
}
}
''')
}
}
}The first run of the seed job failed:
Started by user admin
Running as SYSTEM
Building on the built-in node in workspace /home/sid/workspace/seed
[…]
Checking out Revision f53fc272676b9f697065b53cd913336e2dcd1bc1 (origin/main)
[…]
Commit message: "Add payments jobs"
First time build. Skipping changelog.
Processing DSL script jobs/payments.groovy
ERROR: script not yet approved for use
Finished: FAILUREJob DSL scripts can do anything inside Jenkins, so by default a script loaded from a
workspace needs an administrator's approval (Manage Jenkins → In-process Script
Approval) before it may run, and every change to it needs approval again. Scripts in
JCasC's own jobs: key are not affected because they come from the administrator's
configuration. You have two choices:
- Keep script security on and approve each new script version. Safe, but it adds friction to every change.
- Turn script security off for Job DSL, and protect the
ci-jobsrepository instead: only people you would trust with admin rights may merge to it.
I chose the second, with a fourth file in casc/:
security:
globalJobDslSecurityConfiguration:
useScriptSecurity: falseAfter a reload, the second seed run created the job:
Started by user admin
Running as SYSTEM
Building on the built-in node in workspace /home/sid/workspace/seed
[…]
Commit message: "Add payments jobs"
> git rev-list --no-walk f53fc272676b9f697065b53cd913336e2dcd1bc1 # timeout=10
Processing DSL script jobs/payments.groovy
Added items:
GeneratedJob{name='payments/release-notes'}
Finished: SUCCESSAnd the new job runs like any other:
[2026-11-10T06:26:20.282Z] Started by user admin
[2026-11-10T06:26:20.471Z] [Pipeline] Start of Pipeline
[2026-11-10T06:26:20.814Z] [Pipeline] node
[2026-11-10T06:26:20.866Z] Running on Jenkins in /home/sid/workspace/payments/release-notes
[2026-11-10T06:26:20.907Z] [Pipeline] {
[2026-11-10T06:26:21.006Z] [Pipeline] stage
[2026-11-10T06:26:21.032Z] [Pipeline] { (Notes)
[2026-11-10T06:26:21.155Z] [Pipeline] echo
[2026-11-10T06:26:21.181Z] Collecting release notes for payments-api on built-in
[2026-11-10T06:26:21.207Z] [Pipeline] }
[2026-11-10T06:26:21.304Z] [Pipeline] // stage
[2026-11-10T06:26:21.344Z] [Pipeline] }
[2026-11-10T06:26:21.443Z] [Pipeline] // node
[2026-11-10T06:26:21.498Z] [Pipeline] End of Pipeline
[2026-11-10T06:26:21.619Z] Finished: SUCCESSremovedJobAction('DELETE') in the seed job tells Job DSL to delete jobs that it created
earlier but whose definitions have since disappeared from the repository; the default,
IGNORE, leaves them behind. Note also that exporting the configuration does not include
jobs. The export I took from this controller had no jobs: section at all: jobs live in
your Job DSL scripts, nowhere else.
Reloading, and why UI changes do not stick
You can apply a changed configuration without restarting in three ways: the
Manage Jenkins → Configuration as Code page (it shows the current source under
"Reload your configuration or update configuration source.", next to an
Export configuration button), the CLI command reload-jcasc-configuration, or a POST
to /configuration-as-code/reload, which is what I used (with the crumb shown earlier). A reload applies everything in the files again.
Anything the files set is reset to the file's value:
curl -s -b cookies.txt -u "admin:$JENKINS_ADMIN_PASSWORD" -H "$CRUMB" -X POST \
--data-urlencode 'script=Jenkins.get().setSystemMessage("Deploy freeze until Friday"); println Jenkins.get().systemMessage' \
http://localhost:8093/scriptText
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/api/json?tree=description" | jq -r .description
curl -s -o /dev/null -w "reload: HTTP %{http_code}\n" -b cookies.txt -u "admin:$JENKINS_ADMIN_PASSWORD" -H "$CRUMB" -X POST http://localhost:8093/configuration-as-code/reload
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/api/json?tree=description" | jq -r .descriptionDeploy freeze until Friday
Deploy freeze until Friday
reload: HTTP 302
payments CI. Managed by JCasC: changes made in the UI are overwritten on the next reload.The script console here stands in for someone editing Manage Jenkins → System in the
browser; the effect is the same. The hotfix survived until the next reload, then vanished.
That is the point of JCasC, and also its sharpest edge: settings that are not in your
files are left alone, so a controller can still drift in everything you have not
codified. Two habits help. Put the message from the systemMessage above (or something
like it) on every managed controller so people know not to click, and restrict
Overall/Administer to the people who maintain the files.
Plugins as code with plugins.txt
JCasC configures plugins; it does not install them. The Plugin Installation Manager
(jenkins-plugin-manager.jar, called jenkins-plugin-cli inside the official Docker
image) installs a list of plugins with their dependencies. A quick way to get the list
from a controller that already works:
curl -s -u "admin:$PASS" "http://localhost:8090/pluginManager/api/json?depth=1&tree=plugins%5BshortName,version%5D" |
jq -r '.plugins[] | "\(.shortName):\(.version)"' | sort > plugins-all.txt
wc -l plugins-all.txt
head -5 plugins-all.txt99 plugins-all.txt
antisamy-markup-formatter:173.v680e3a_b_69ff3
apache-httpcomponents-client-4-api:4.5.14-269.vfa_2321039a_83
asm-api:9.11.1-226.vff833a_e4c58e
authentication-tokens:1.144.v5ff4a_5ec5c33
bootstrap5-api:5.3.8-1048.va_c299057e35cThat list includes every dependency, which makes upgrades painful: you would have to bump
library plugins by hand. Keep only the plugins you chose and let the tool resolve the
rest. This is the payments controller's plugins.txt, with versions pinned:
cloudbees-folder:6.1107.v31f8955765c8
configuration-as-code:2147.v8a_8d38668c72
credentials-binding:728.v902a_273b_8947
git:5.11.0
job-dsl:3732.v9a_c49a_61a_313
matrix-auth:3.3
ssh-slaves:3.1097.v868116049892
timestamper:1.30
workflow-aggregator:608.v67378e9d3db_1
workflow-multibranch:842.v3a_b_59b_57b_e6e--no-download --list shows what the tool would install without downloading anything:
java -jar jenkins-plugin-manager.jar --war jenkins.war --plugin-file plugins.txt \
--plugin-download-directory /dev/shm/plugins --no-download --list
Installed plugins:
-none-
Bundled plugins:
-none-
All requested plugins:
antisamy-markup-formatter 173.v680e3a_b_69ff3
apache-httpcomponents-client-4-api 4.5.14-269.vfa_2321039a_83
asm-api 9.11.1-226.vff833a_e4c58e
bootstrap5-api 5.3.8-1048.va_c299057e35c
bouncycastle-api 2.30.1.86.2-310.v4655f6742752
branch-api 2.1303.v9f3b_95dc329d
[…]
credentials 1514.vb_01eb_014e7d4
credentials-binding 728.v902a_273b_8947
[…]
job-dsl 3732.v9a_c49a_61a_313
[…]
ssh-credentials 372.va_250881b_08cd
[…]Ten requested plugins expand to dozens once dependencies are resolved. It took 4.4 seconds
and needed network access to the update center. Without --no-download, the same command
fills the download directory with .jpi files, ready to become JENKINS_HOME/plugins.
--available-updates --output txt prints the list with newer versions substituted; when I
ran it, every pin was current, so it printed the same ten lines back.
A complete, reproducible controller
Put the pieces together and the controller is a directory in Git:
payments-ci/
├── Dockerfile
├── plugins.txt
├── casc/
│ ├── jenkins.yaml
│ ├── credentials.yaml
│ ├── jobs.yaml
│ └── security.yaml
├── start-controller.sh
└── validate-casc.shWith Docker, the image pins the Jenkins version, installs the plugins at build time, and carries the configuration. Secrets are passed at run time:
FROM jenkins/jenkins:2.580.2-lts-jdk21
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
ENV CASC_JENKINS_CONFIG=/var/jenkins_casc
COPY --chown=jenkins:jenkins plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txt
COPY --chown=jenkins:jenkins casc/ /var/jenkins_casc/docker build -t payments-ci:2.580.2 .
docker run -d --name payments-ci -p 8080:8080 \
--env-file secrets.env \
-v payments-ci-home:/var/jenkins_home \
payments-ci:2.580.2My lab has no Docker, so I did not build or run this image. What I did run is the same
design with the WAR: a pinned jenkins.war (2.580.2), the plugin set, the casc/
directory, and start-controller.sh passing secrets through the environment. Starting it
against an empty JENKINS_HOME produced every job, credential, user and node shown in
this article, in 14 seconds. That is the test that matters: if you cannot delete
JENKINS_HOME (apart from history) and get the same controller back, the configuration is
not complete yet.
A change to the configuration should go through a pull request like any other code, and CI should boot a disposable controller with the proposed files before anyone merges. Exercise 4 builds that check.
Backups and upgrades
JCasC changes what a backup is for. The configuration, jobs and plugin list are in Git, so
the controller's disk only holds what Git cannot: build history, secrets/ (the keys that
decrypt anything stored in JENKINS_HOME), user API tokens and fingerprints. A backup of
the lab controller that skips everything reproducible:
tar --exclude=./plugins --exclude=./war --exclude=./workspace --exclude=./caches --exclude=./logs \
-czf /dev/shm/jenkins-home-backup.tgz -C home .
ls -lh /dev/shm/jenkins-home-backup.tgz
tar -tzf /dev/shm/jenkins-home-backup.tgz | grep -E '^\./(secrets/|credentials.xml|config.xml|jobs/payments/jobs/nightly-db-report/|users/)' | head -20-rw-r--r-- 1 sid sid 746K Nov 10 01:27 /dev/shm/jenkins-home-backup.tgz
./jobs/payments/jobs/nightly-db-report/
./jobs/payments/jobs/nightly-db-report/config.xml
./secrets/
./secrets/com.cloudbees.plugins.credentials.SecretBytes.KEY
./secrets/master.key
./secrets/jenkins.security.csp.ReportingContext.key
./secrets/hudson.console.ConsoleNote.MAC
./secrets/hudson.util.Secret
./secrets/org.jenkinsci.main.modules.instance_identity.InstanceIdentity.KEY
./secrets/hudson.model.User.DIRNAMES
./secrets/jenkins.model.Jenkins.crumbSalt
./secrets/hudson.model.Job.serverCookie
./users/
./users/admin_6069a56e82ab68908943630ff394a55bef2203763f3d5ee896aa2af060afc19a/
./users/admin_6069a56e82ab68908943630ff394a55bef2203763f3d5ee896aa2af060afc19a/config.xml
./users/dev_b5fdaf9e756892181d4207d8e9ed9f8a2bae121211212cb9c80970d56c82c9b3/
./users/dev_b5fdaf9e756892181d4207d8e9ed9f8a2bae121211212cb9c80970d56c82c9b3/config.xml
./credentials.xml
./config.xml746 KB, against 66 MB for the unpacked WAR and 206 MB of plugins that were left out because
the Dockerfile or plugins.txt rebuilds them. The backup still contains secrets/ and
credentials.xml, so protect it like a password vault. Scheduling backups and testing a
restore are covered in
Installing Jenkins.
Upgrades become a code change:
- On a branch, bump the image tag (or the WAR) and the versions in
plugins.txt. - Boot a disposable controller from the branch (Exercise 4) and run a few real jobs on it. A plugin upgrade that renames a configuration key shows up here as a failed boot, not as a broken production controller.
- Merge, build the image, take a backup of
JENKINS_HOME, and replace the running container. - To roll back, run the previous image tag against the backup.
To see which version a WAR is, and which version last ran against a home:
java -jar jenkins.war --version2.580.2Where you'll use this
- Disaster recovery: rebuilding a controller becomes "deploy the image, restore history", measured in minutes.
- Identical environments: a staging controller built from the same files as production, where plugin upgrades are tried first.
- Many controllers: platform teams that give each department its own controller keep one set of shared YAML plus a small per-team file.
- Audits: every permission change is a reviewed commit with an author and a date.
- Self-service jobs: teams own their Job DSL scripts in a seed repository and never need admin rights to add a pipeline.
The complete example is the one this article built: the four files in casc/, the
plugins.txt, the start script and the Dockerfile above, plus the ci-jobs repository for
the seed job. Together they recreated the payments controller from an empty
JENKINS_HOME.
Common mistakes
A typo in a key stops the controller from starting
JCasC rejects unknown keys. A one-letter typo in systemMessage, applied at startup, does
not produce a warning. The controller refuses to boot:
2026-11-10 06:28:10.770+0000 [id=60] SEVERE jenkins.InitReactorRunner$1#onTaskFailed: Failed ConfigurationAsCode.init
2026-11-10 06:28:10.772+0000 [id=38] SEVERE hudson.util.BootFailure#publish: Failed to initialize Jenkins
io.jenkins.plugins.casc.UnknownAttributesException: jenkins: Invalid configuration elements for type: class jenkins.model.Jenkins : systemMesage.The same typo applied by a reload on a running controller leaves the old configuration in place, and the reload request answered HTTP 200 instead of the usual 302:
reload: HTTP 200
Invalid configuration elements for type: with the full UnknownAttributesException line in jenkins.log. Do not treat "the
request succeeded" as "the configuration applied"; check the log, or validate before
merging.
An unset variable becomes an empty secret
I added a credential that uses ${NPM_TOKEN} without defining the variable, then reloaded.
The reload succeeded, the log warned, and the credential was created with an empty secret:
2026-11-10 06:26:38.097+0000 [id=25] WARNING i.j.p.c.SecretSourceResolver$UnresolvedLookup#lookup: Configuration import: Found unresolved variable 'NPM_TOKEN'. Will default to empty stringnpm-token exists: true, secret length: 0Builds using that credential fail later, far from the cause. Grep the startup log for
unresolved variable as part of every deployment, or let your validation step fail on it.
Committing an export with secrets in it
An export of a controller with credentials contains their values in encrypted form:
- string:
description: "SonarQube analysis token"
id: "sonar-token"
scope: GLOBAL
secret: "{AQAAABAAAAAw77Achoq54lIstB7v6WcvfhIFs9MZyEedLSCdB+YAIYlcQ/yG2YO6FK9EF3PgkdVk1ggzu23C/tb7bg9MnD+4jw==}"That value can be decrypted by that controller's secrets/ keys, and is useless anywhere
else. Committing it is both a leak (for anyone with a backup of the controller) and a bug
(a rebuilt controller cannot read it). Replace every secret in an export with a
${VARIABLE} before it goes into Git.
Summary
- JCasC applies YAML from
CASC_JENKINS_CONFIG(a file, a directory of YAML files, or a URL) at startup and on reload. Root keys:jenkins,credentials,unclassified,tool,security, plusjobsfrom Job DSL. - Learn the schema from
export-configuration, but commit only the settings you decided on. Setunclassified.location.url; the CLI refuses WebSocket connections without it. - Keep secrets out of the YAML with
${VAR},${VAR:-default},${readFile:…}and${readFileBase64:…}. Environment variables are read only at process start; an unset variable becomes an empty string with only a warning. - Job DSL creates jobs from
jobs:in JCasC or from a seed job reading a repository. Seed scripts need approval unless Job DSL script security is turned off, which shifts the trust to whoever can merge to that repository. - A reload resets everything the files define, so UI changes to managed settings vanish; settings the files do not mention can still drift.
plugins.txtshould list the plugins you chose, pinned; the Plugin Installation Manager resolves dependencies.- A typo in a key stops a controller from booting; boot a disposable controller with every
proposed change before merging, and keep
secrets/in your backups.
Exercises
Add a secret text credential npm-token whose value comes from the environment variable
NPM_TOKEN. Set the variable, start (or restart) the controller, and prove that the
credential exists with a non-empty secret without printing the secret.
Hint
Add the variable to secrets.env. A reload is not enough for a new environment variable.
The script console can look the credential up and print the secret's length.
Show Solution
Appended to the credentials list in casc/credentials.yaml:
- string:
scope: GLOBAL
id: "npm-token"
description: "npm publish token"
secret: "${NPM_TOKEN}"echo "NPM_TOKEN=npm_4kQ9zR2mX7vL1pT8wY3nB6cJ0hF5dG" >> secrets.env
./start-controller.shThen, in Manage Jenkins → Script Console (I sent it to /scriptText):
import com.cloudbees.plugins.credentials.CredentialsProvider
import org.jenkinsci.plugins.plaincredentials.StringCredentials
def c = CredentialsProvider.lookupCredentialsInItemGroup(StringCredentials, Jenkins.get(), null, null).find { it.id == "npm-token" }
println "npm-token exists: ${c != null}, secret length: ${c?.secret?.plainText?.length()}"npm-token exists: true, secret length: 34Before the variable was set, the same check printed secret length: 0, as shown in
Common mistakes.
Add a pipeline job payments/smoke-test with an inline Jenkinsfile that echoes the
staging health URL. Add it to jobs.yaml, apply it with a reload (no restart), confirm it
appears in the folder, and build it.
Show Solution
Appended to casc/jobs.yaml:
- script: |
pipelineJob('payments/smoke-test') {
description('Hits the staging health endpoint after each deploy')
definition {
cps {
sandbox(true)
script('''
pipeline {
agent any
stages {
stage('Smoke') {
steps {
echo "checking https://staging.payments.example.com/health"
}
}
}
}
'''.stripIndent())
}
}
}curl -s -o /dev/null -w "reload: HTTP %{http_code}\n" -b cookies.txt -u "admin:$JENKINS_ADMIN_PASSWORD" -H "$CRUMB" -X POST http://localhost:8093/configuration-as-code/reload
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" "http://localhost:8093/job/payments/api/json?tree=jobs%5Bname%5D" | jq -r '.jobs[].name'
curl -s -o /dev/null -w "build: HTTP %{http_code}\n" -b cookies.txt -u "admin:$JENKINS_ADMIN_PASSWORD" -H "$CRUMB" -X POST "http://localhost:8093/job/payments/job/smoke-test/build?delay=0sec"
curl -s -u "admin:$JENKINS_ADMIN_PASSWORD" http://localhost:8093/job/payments/job/smoke-test/1/consoleTextreload: HTTP 302
nightly-db-report
payments-api
release-notes
smoke-test
build: HTTP 201
[2026-11-10T06:28:52.020Z] Started by user admin
[2026-11-10T06:28:52.764Z] [Pipeline] Start of Pipeline
[2026-11-10T06:28:54.325Z] [Pipeline] node
[2026-11-10T06:28:54.375Z] Running on Jenkins in /home/sid/workspace/payments/smoke-test
[…]
[2026-11-10T06:28:54.954Z] checking https://staging.payments.example.com/health
[…]
[2026-11-10T06:28:55.715Z] Finished: SUCCESSrelease-notes is still there: it was created by the seed job, and a JCasC reload does
not touch jobs it did not define.
On a controller managed by JCasC, change the system message through the script console (or the System page), confirm the change, reload the configuration, and check the message again. Then explain how you would make the "deploy freeze" message stick properly.
Show Solution
The commands and output are in "Reloading, and why UI changes do not stick": the message
read "Deploy freeze until Friday" until the reload, then returned to the value in
jenkins.yaml.
To make it stick, change systemMessage in jenkins.yaml through a pull request and
reload. For a message that changes often, make it a variable with a default,
systemMessage: "${CI_BANNER:-payments CI. Managed by JCasC.}", so operators can set it in
the environment without editing YAML. Remember that environment variables need a restart,
so for something you toggle during an incident, editing the file and reloading is faster.
Write validate-casc.sh CASC_DIR for your CI system. It must boot a disposable
controller with the given configuration directory on a spare port, wait until it is
either fully up or has failed, print the relevant error on failure, stop the controller,
delete its temporary home, and exit 0 or 1. Test it with a copy of jenkins.yaml that
contains the systemMesage typo, then with the typo fixed.
Hint
Watch the log for Jenkins is fully up and running (success) or
UnknownAttributesException, ConfiguratorException and Failed to initialize
(failure). Hard-link the plugins directory into the temporary home so each run costs no
disk space.
Show Solution
#!/usr/bin/env bash
# validate-casc.sh CASC_DIR: boot a disposable controller with this configuration,
# report whether it came up cleanly, then throw it away.
set -uo pipefail
CASC_DIR=$(realpath "$1")
: "${JENKINS_WAR:?set JENKINS_WAR to the jenkins.war you run in production}"
: "${PLUGINS_DIR:?set PLUGINS_DIR to a plugins directory built from plugins.txt}"
TMP_HOME=$(mktemp -d /tmp/casc-check.XXXXXX)
cp -al "$PLUGINS_DIR" "$TMP_HOME/plugins"
JENKINS_HOME=$TMP_HOME CASC_JENKINS_CONFIG=$CASC_DIR \
java -Xmx512m -Djenkins.install.runSetupWizard=false -jar "$JENKINS_WAR" \
--httpPort=8094 --httpListenAddress=127.0.0.1 > "$TMP_HOME/boot.log" 2>&1 &
pid=$!
status=1
for _ in $(seq 1 90); do
if grep -q 'Jenkins is fully up and running' "$TMP_HOME/boot.log"; then status=0; break; fi
if grep -qE 'ConfiguratorException|UnknownAttributesException|Failed to initialize' "$TMP_HOME/boot.log"; then break; fi
kill -0 "$pid" 2>/dev/null || break
sleep 2
done
if [ "$status" -eq 0 ]; then
echo "OK: $CASC_DIR applied cleanly"
else
echo "FAILED: $CASC_DIR"
grep -E 'Exception: |SEVERE' "$TMP_HOME/boot.log" | grep -v '^\s*at ' | sort -u | head -5
fi
kill "$pid" 2>/dev/null; wait "$pid" 2>/dev/null
rm -rf "$TMP_HOME"
exit "$status"export JENKINS_WAR=/opt/jenkins/jenkins.war PLUGINS_DIR=$PWD/home/plugins
set -a; source secrets.env; set +a
./validate-casc.sh proposed; echo "exit=$?"
sed -i 's/ systemMesage:/ systemMessage:/' proposed/jenkins.yaml
./validate-casc.sh proposed; echo "exit=$?"FAILED: /home/sid/controller/proposed
2026-11-10 06:28:10.770+0000 [id=60] SEVERE jenkins.InitReactorRunner$1#onTaskFailed: Failed ConfigurationAsCode.init
2026-11-10 06:28:10.772+0000 [id=38] SEVERE hudson.util.BootFailure#publish: Failed to initialize Jenkins
io.jenkins.plugins.casc.UnknownAttributesException: jenkins: Invalid configuration elements for type: class jenkins.model.Jenkins : systemMesage.
exit=1
OK: /home/sid/controller/proposed applied cleanly
exit=0Secrets must be present for the check, because JCasC resolves them while applying; in CI,
use dummy values of the right shape. A useful extension is to also fail when the log
contains unresolved variable, which catches the empty-secret mistake.
Tested with: Jenkins 2.580.2 (WAR) on OpenJDK 21, Ubuntu 24.04 under WSL2, with
Configuration as Code 2147.v8a_8d38668c72, Job DSL 3732.v9a_c49a_61a_313, Matrix
Authorization Strategy 3.3 and Plugin Installation Manager 2.16.0, November 2026. Every
YAML file, script and command was run against a throwaway controller on port 8093, started
fresh from an empty JENKINS_HOME (plugins hard-linked from an existing controller),
stopped after each test and then deleted. To stay within the lab's memory, I ran the
multibranch, seed and smoke-test builds on the built-in node (BUILTIN_EXECUTORS=1)
instead of connecting linux-agent-1. The Dockerfile was not built because the lab has no
Docker. The reload button and other UI paths were not clicked through; reloads were done
with the REST endpoint. Plugin resolution used --no-download, so no plugins were
downloaded. Paths from the test machine's scratch directories are shown shortened to /home/sid/….
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Jenkins tutorial here is tested end to end before publishing.