Jenkins Configuration as Code

Clicking through the Jenkins settings pages works for one small server. It fails when you rebuild a server after a crash, clone a setup for a second team, or try to remember who changed a security option last month. Jenkins Configuration as Code, shortened to JCasC, stores the whole setup in a readable YAML file that you keep in Git.

The Layman's View

Picture two ways to furnish a flat. In the first, you walk through rooms and place furniture from memory. In the second, you hold a floor plan that lists every item and its position. Anyone can rebuild the flat from the plan. JCasC is the floor plan of your Jenkins server.

Manual Setup Versus JCasC

MANUAL                               JCasC
------                               -----
Click, click, click                  jenkins.yaml in Git
No history of changes                Every change in commit history
Hard to repeat                       Rebuild in minutes
Different on each server             Identical on every server

Installing the Plugin

Open Manage Jenkins, then Plugins, and install Configuration as Code. After a restart, a new entry named Configuration as Code appears under Manage Jenkins. The page lets you view the current configuration, reload a file, and export your present settings as YAML.

A First jenkins.yaml

jenkins:
  systemMessage: "Welcome to the team Jenkins server"
  numExecutors: 2
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "${ADMIN_PASSWORD}"
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false

unclassified:
  location:
    url: "https://jenkins.example.com/"

Each top-level key matches a section of the Jenkins settings. The jenkins block controls core options, and the unclassified block holds plugin and location settings.

Telling Jenkins Where the File Lives

Jenkins finds the file through the environment variable CASC_JENKINS_CONFIG. Set it to a file path, a folder, or a web address.

export CASC_JENKINS_CONFIG=/var/jenkins_home/casc/jenkins.yaml

When the value points to a folder, Jenkins merges every YAML file inside it. Teams use this feature to split settings into files such as security.yaml, agents.yaml, and tools.yaml.

Keeping Secrets Out of the File

The sample above reads the password from ${ADMIN_PASSWORD}. Jenkins fills the placeholder from an environment variable, a Docker secret, or a Kubernetes secret at startup. The YAML file stays safe to commit because it never holds the real value.

Source	Syntax
Environment variable	${ADMIN_PASSWORD}
Default value	${ADMIN_PASSWORD:-changeme}
File-based secret	${readFile:/run/secrets/admin_pw}

Adding Credentials, Tools, and Agents

credentials:
  system:
    domainCredentials:
      - credentials:
          - usernamePassword:
              scope: GLOBAL
              id: "git-login"
              username: "ci-bot"
              password: "${GIT_PASSWORD}"

tool:
  git:
    installations:
      - name: "Default"
        home: "git"
  maven:
    installations:
      - name: "Maven3"
        properties:
          - installSource:
              installers:
                - maven:
                    id: "3.9.6"

Creating Jobs With Job DSL

JCasC pairs with the Job DSL plugin to create jobs from code. A seed job definition inside jenkins.yaml builds a pipeline job at startup.

jobs:
  - script: >
      pipelineJob('demo-pipeline') {
        definition {
          cpsScm {
            scm {
              git('https://github.com/example/demo.git')
            }
            scriptPath('Jenkinsfile')
          }
        }
      }

The Rebuild Workflow

 Edit jenkins.yaml
        |
        v
 Commit and push to Git
        |
        v
 Review by teammate
        |
        v
 Merge
        |
        v
 Reload in Jenkins  (Manage Jenkins -> Configuration as Code -> Reload)
        |
        v
 Server matches the file

Validating Before You Apply

A typing mistake in YAML can stop Jenkins from starting. Use the Configuration as Code page and press Check New Configuration to test a file without applying it. A pull request pipeline can run the same check automatically.

Benefits for Teams

• Disaster recovery takes minutes, since a new server reads the file and matches the old one.
• Code review applies to settings, so risky changes get a second pair of eyes.
• Test and production servers share one base file with small differences.
• New hires read the YAML to learn how the server works.

Cautions

Avoid Mixed Control

Editing a setting through the web page while JCasC manages it leads to surprise rollbacks at the next reload. Choose one source of truth and tell the team.

Pin Plugin Versions

A plugin upgrade can rename a setting. List plugin versions in a plugins.txt file and test upgrades on a staging server first.

Protect the Repository

Anyone who can change jenkins.yaml can change who administers Jenkins. Limit write access to trusted people.

With JCasC in place, your Jenkins server becomes a reproducible product instead of a hand-built one-off.