TopolearnHand-configured controllers drift and can't be rebuilt after a disaster; code-defined ones can.
The Configuration as Code plugin (JCasC) reads YAML describing the controller: system settings, security realm, authorization, credentials, clouds, global libraries and tool installations. Point it at files with the CASC_JENKINS_CONFIG environment variable (a file, directory or URL). On startup, or when you click Reload existing configuration, Jenkins applies it. Manage Jenkins, Configuration as Code, View Configuration exports the current setup as a starting point.
Secrets in JCasC YAML are referenced as ${VAR} and resolved from environment variables, files (such as Kubernetes or Docker secrets) or secret managers, never written in clear text.
Plugins are the other half of the state. List them with pinned versions in plugins.txt and install them at image build time with jenkins-plugin-cli. Together this gives an immutable controller: a Docker image containing Jenkins, plugins and JCasC files, plus a volume only for build history. Upgrades become a reviewed image change that you can test and roll back.
Jobs themselves come from code too: Multibranch and Organization Folders discover Jenkinsfiles, and the Job DSL plugin can create other jobs from scripts. The goal is that nothing important exists only in the UI.
Example
# Dockerfile for an immutable controller
FROM jenkins/jenkins:lts-jdk21
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false" \
CASC_JENKINS_CONFIG=/casc
COPY plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txt
COPY casc/ /casc/
# plugins.txt # casc/jenkins.yaml
# configuration-as-code:latest # jenkins:
# workflow-aggregator:latest # numExecutors: 0
# git:latest # securityRealm:
# (pin exact versions in prod) # local:
# # users:
# # - id: admin
# # password: ${ADMIN_PASSWORD}Remember
- JCasC applies YAML from CASC_JENKINS_CONFIG at startup or reload
- Pin plugins in plugins.txt and install with jenkins-plugin-cli
- Secrets are ${VAR} references resolved at load time
Watch out for
- Tweaking settings in the UI on a JCasC-managed controller; the next reload overwrites them.