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:

WhatFileTool
Which Jenkins and pluginsplugins.txt (plus a pinned WAR or image tag)Plugin Installation Manager
How Jenkins is configuredjenkins.yamlConfiguration as Code plugin
Which jobs existJob DSL scriptsJob DSL plugin
Secretsenvironment variables or files, never GitJCasC 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: loggedInUsersCanDoAnything

JCasC 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-i
CLI 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: nosniff

The 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.yaml
reload: HTTP 302
Authenticated as: admin
Authorities:
  authenticated
  FACTOR_PASSWORD
224 exported.yaml

Two 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 keyCoversUI equivalent
jenkinscore settings: executors, security realm, authorization, nodes, clouds, viewsSystem, Security, Nodes
credentialsthe global credential storeCredentials
unclassifiedsettings contributed by plugins: Jenkins URL, timestamper, mailer, build discarders, shared librariesSystem (most of the page)
tooltool installations: Git, JDK, MavenTools
securitysecurity settings from plugins, such as Job DSL script securitySecurity
jobsJob 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 casc
casc
├── credentials.yaml
├── jenkins.yaml
└── jobs.yaml
 
1 directory, 3 files

jenkins.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 of BUILTIN_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.local creates 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) gives admin everything and dev read and build permission only.
  • nodes defines the agent linux-agent-1, the same thing as Nodes → New Node in the UI. The agent process still has to be started on the agent machine.
  • unclassified sets 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:

SyntaxResolves 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/kubeconfig

Environment 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.sh
started 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 running

Now 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 403

The 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 executor

That 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: FAILURE

Job 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:

  1. Keep script security on and approve each new script version. Safe, but it adds friction to every change.
  2. Turn script security off for Job DSL, and protect the ci-jobs repository 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: false

After 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: SUCCESS

And 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: SUCCESS

removedJobAction('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 .description
Deploy 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.txt
99 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_c299057e35c

That 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.sh

With 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.2

My 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.xml

746 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:

  1. On a branch, bump the image tag (or the WAR) and the versions in plugins.txt.
  2. 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.
  3. Merge, build the image, take a backup of JENKINS_HOME, and replace the running container.
  4. 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 --version
2.580.2

Where 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 string
npm-token exists: true, secret length: 0

Builds 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, plus jobs from Job DSL.
  • Learn the schema from export-configuration, but commit only the settings you decided on. Set unclassified.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.txt should 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

Exercise 1: A credential from the environmenteasy

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.sh

Then, 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: 34

Before the variable was set, the same check printed secret length: 0, as shown in Common mistakes.

Exercise 2: Add a job without restartingmedium

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/consoleText
reload: 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: SUCCESS

release-notes is still there: it was created by the seed job, and a JCasC reload does not touch jobs it did not define.

Exercise 3: Watch a manual change disappearmedium

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.

Exercise 4: Validate a configuration before it shipshard

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=0

Secrets 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/….

Was this page helpful?
The Dark Debugger

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.