Configure and Explore JCasC

Jenkins Configuration as Code (JCasC) lets you express a Jenkins instance and many plugin settings as human-readable YAML. Using JCasC makes Jenkins configuration repeatable, auditable, and suitable for version control — ideal for infrastructure-as-code workflows and CI/CD pipelines. This guide shows how to install the JCasC plugin, inspect the auto-generated YAML for a running instance, and apply changes from a YAML file stored on the controller or an external source.

What you’ll learn

Installing the Configuration as Code plugin
Where JCasC looks for configuration files and environment variables
Viewing the auto-generated YAML export
Editing and applying JCasC YAML on the controller
Best practices, validation, and troubleshooting

Installation and official docs

Install the plugin from Manage Jenkins → Manage Plugins → Available → Configuration as Code. Official resources:

Plugin page: https://plugins.jenkins.io/configuration-as-code/
Examples & repo: https://github.com/jenkinsci/configuration-as-code-plugin

Common configuration locations and environment variables

Purpose	Examples / Notes
Environment variable to point at JCasC config directory	`CASC_JENKINS_CONFIG: /var/jenkins_home/casc_configs`
JVM option alternative	`JENKINS_JAVA_OPTIONS: "-Dcasc.jenkins.config=/jenkins/casc_configs"`
Typical file locations the plugin can load	`/var/jenkins_home/casc_config/jenkins.yaml`, `https://acme.org/jenkins.yaml`
Supported extensions	`.yml`, `.yaml`, `.YAML`
Default fallback	`$JENKINS_HOME/jenkins.yaml`

Example environment snippet (for clarity):

CASC_JENKINS_CONFIG: /var/jenkins_home/casc_configs
# example file paths or URLs the plugin can load from:
# /var/jenkins_home/casc_config/jenkins.yaml
# https://acme.org/jenkins.yaml
# accepted extensions: .yml, .yaml, .YAML
# environment option: casc.jenkins.config
JENKINS_JAVA_OPTIONS: "-Dcasc.jenkins.config=/jenkins/casc_configs"
# default fallback:
# $JENKINS_HOME/jenkins.yaml

After installing the plugin you may need to restart Jenkins. Once back up, go to Manage Jenkins → Configuration as Code. From that page you can:

View the current configuration exported to YAML (auto-generated from the running instance).
Point Jenkins to a file path, HTTP(S) URL, or Git repository with the YAML and apply it.
Download the current configuration, reload a configuration, or inspect links to documentation and the JSON schema.

Viewing the current configuration (auto-generated YAML)

When you click “View Configuration” JCasC renders a comprehensive YAML representation of the running Jenkins instance. The YAML includes core settings, tool installations, credentials, plugin global configuration (under unclassified), and more. Representative excerpt for top-level and core settings:

providerFilter: "none"
typeFilter: "none"
appearance:
  pipelineGraphView:
    showGraphOnBuildPage: true
    showGraphOnJobPage: true
prism:
  theme: PRISM
themeManager:
  disableUserThemes: false
  theme: "darkSystem"
security:
  apiToken:
    creationOfLegacyTokenEnabled: false
    tokenGenerationOnCreationEnabled: false
  usageStatisticsEnabled: true
copyartifact:
  mode: PRODUCTION
cps:
  nodeSandbox: false
gitHooks:
  allowedOnAgents: false
  allowedOnController: false
gitHostKeyVerificationConfiguration:
  sshHostKeyVerificationStrategy: "knownHostsFileVerificationStrategy"
ssh:
  port: 1
unclassified:
  audit-trail:
    displayUserName: true
    logBuildCause: true
    logCredentialsUsage: true
  loggers:
    - logFileDailyRotation:

Representative excerpt for tool installations:

name: "Default"
maven:
  installations:
    - name: "M398"
      properties:
        - installSource:
            installers:
              - maven:
                  id: "3.9.8"
mavenGlobalConfig:
  globalSettingsProvider: "standard"
  settingsProvider: "standard"
nodejs:
  installations:
    - name: "nodejs-22-6-0"
      properties:
        - installSource:
            installers:
              - nodeJSInstaller:
                  id: "22.6.0"
  npmPackagesRefreshHours: 72
sonarRunnerInstallation:
  installations:
    - name: "sonarqube-scanner-610"
      properties:
        - installSource:
            installers:
              - sonarRunnerInstaller:
                  id: "6.1.0.4477"

Credentials representation and sensitive data

Credentials are included in the YAML export in declarative form. Sensitive values appear as encrypted blobs or hashed tokens in the generated YAML — the real export hides plaintext secrets. Representative credentials excerpt (sensitive fields shown as encrypted blobs in real exports):

credentials:
  system:
    domainCredentials:
      - credentials:
        - usernamePassword:
            description: "Gitea Server Credentials"
            id: "gitea-server-creds"
            username: "gitea-admin"
            password: "{AQAAABAAAAAQA4e7WfYLRu0yZL9NsHsLaqohKKpJFtItDGTyKUsxqCOU=}"
            scope: GLOBAL
        - usernamePassword:
            description: "Credentials for MongoDB"
            id: "mongo-db-credentials"
            username: "superuser"
            password: "{AQAAABAAAAAQFpgIHj2LB26zTPKnU+rDyr/G7Vm9oalKU8x8Rcp0iE0=}"
            scope: GLOBAL
        - string:
            description: "Mongo Database Username"
            id: "mongo-db-username"
            secret: "{AQAAABAAAAAQF0khJHh3HoKSatkFUUT2Y0YBQsY4d8tgCGOfpOBoBk0=}"
            scope: GLOBAL
        - string:
            description: "Mongo Database Password"
            id: "mongo-db-password"
            secret: "{AQAAABAAAAAQpXMp0KYcy2Hmc9h0VksHvChKdk8C9zO7YLPCyZ30t64=}"
            scope: GLOBAL
        - string:
            description: "Sonarqube Server Token"
            id: "sonar-qube-token"
            scope: GLOBAL

Never store raw plaintext secrets in repository-controlled JCasC YAML. Use Jenkins Credentials, external secret stores, or encrypted credentials. If you must store secrets, ensure they are encrypted and access is tightly controlled.

What else is included in the YAML export

The JCasC export can include:

Jenkins core configuration: agent protocols (JNLP, Connect), authorization strategy (Global Matrix, etc.), security realm, system message, node definitions, health monitors, primary view.
Unclassified section: plugin-specific global configurations such as audit trail, Git servers, SonarQube, Slack notifier, Prometheus, etc.
Tools: Git, Maven, Node.js, SonarQube scanner, Dependency-Check, and other tool installers.

Working with a JCasC YAML file on the controller

A common workflow is to export the YAML, edit it, and place the edited file on the Jenkins controller (often under $JENKINS_HOME or a mounted volume). Then configure JCasC to point to that file. Quick example workflow on the Jenkins controller:

# change to a backup or config directory
cd /var/lib/jenkins/JENKINS_BACKUP

# create/edit the JCasC YAML file
vi jenkins-casc.yaml

Example change inside jenkins-casc.yaml (fragment):

systemMessage: "Loading data from Jenkins JCasC"

Apply the configuration from Manage Jenkins → Configuration as Code:

On the Configuration as Code page, set the “Configuration source” to a path or URL Jenkins can read, for example:
- file:///var/lib/jenkins/JENKINS_BACKUP/jenkins-casc.yaml
- or just jenkins-casc.yaml if the plugin can resolve it in your deployment.
Click “Apply new configuration.” The plugin will validate the YAML first.
If the YAML is valid the plugin will report success and show the timestamp when it was loaded.
Refresh the Jenkins UI to confirm changes (e.g., updated system message).

If the YAML is invalid, JCasC will block the apply and display validation errors. Fix the reported errors and reapply.

JSON schema, downloads, and authoring help

The Configuration as Code page lets you download the current YAML.
A JSON schema is available and useful for tooling, editors, and programmatic validation of JCasC YAML.

Example start of the JCasC JSON schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Jenkins Configuration as Code",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "security": {
      "additionalProperties": false,
      "type": "object",
      "title": "Configuration base for the security classifier",
      "properties": {
        "sshHostKeyVerificationStrategy": {
          "oneOf": [
            { "properties": { "nohostKeyVerificationStrategy": { "$id": "#/definitions/org.jenkinsci.plugins.gitclient.verifier.NoHostKeyVerificationStrategy" } } },
            { "properties": { "manuallyProvidedKeyVerificationStrategy": { "$id": "#/definitions/org.jenkinsci.plugins.gitclient.verifier.ManuallyProvidedKeyVerificationStrategy" } } },
            { "properties": { "acceptFirstConnectionStrategy": { "$id": "#/definitions/org.jenkinsci.plugins.gitclient.verifier.AcceptFirstConnectionStrategy" } } },
            { "properties": { "knownHostsFileVerificationStrategy": { "$id": "#/definitions/org.jenkinsci.plugins.gitclient.verifier.KnownhostsFileVerificationStrategy" } } }
          ],
          "type": "object"
        }
      }
    }
  }
}

Use the schema with editors that support JSON Schema validation (VS Code, JetBrains IDEs) to get autocompletion and inline validation while authoring JCasC YAML.

Troubleshooting and validation tips

Always validate YAML before applying. The JCasC page performs validation and lists problems.
Check jenkins.log for stack traces if applying a configuration fails during runtime.
When a plugin adds new global settings, reconciling YAML may require updating your config or using plugin-specific sections under unclassified.
For large changes, apply incrementally and verify each step in the UI.

Best practices

Keep your JCasC YAML in version control (Git). Avoid storing raw secrets in YAML; use Jenkins Credentials or an external secrets manager. Use the JCasC JSON schema and plugin documentation when authoring complex configurations to minimize validation errors and drift.

Summary

Jenkins Configuration as Code (JCasC) converts the GUI-driven configuration surface area of Jenkins and many plugins into a declarative YAML format. You can export the current configuration, store it in version control, edit it for reproducible changes, and instruct Jenkins to apply a configuration file. For non-trivial Jenkins installations with many plugins, credentials, tools, and cloud integrations, JCasC improves maintainability and reproducibility. Further reading and references:

Jenkins Configuration as Code (plugin): https://plugins.jenkins.io/configuration-as-code/
JCasC GitHub repository and examples: https://github.com/jenkinsci/configuration-as-code-plugin
Jenkins documentation: https://www.jenkins.io/doc/

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring

Backup and Configuration Management

Introduction

Configure and Explore JCasC

What you’ll learn

Installation and official docs

Common configuration locations and environment variables

Viewing the current configuration (auto-generated YAML)

Credentials representation and sensitive data

What else is included in the YAML export

Working with a JCasC YAML file on the controller

JSON schema, downloads, and authoring help

Troubleshooting and validation tips

Best practices

Summary

Watch Video

​What you’ll learn

​Installation and official docs

​Common configuration locations and environment variables

​Viewing the current configuration (auto-generated YAML)

​Credentials representation and sensitive data

​What else is included in the YAML export

​Working with a JCasC YAML file on the controller

​JSON schema, downloads, and authoring help

​Troubleshooting and validation tips

​Best practices

​Summary

Watch Video

What you’ll learn

Installation and official docs

Common configuration locations and environment variables

Viewing the current configuration (auto-generated YAML)

Credentials representation and sensitive data

What else is included in the YAML export

Working with a JCasC YAML file on the controller

JSON schema, downloads, and authoring help

Troubleshooting and validation tips

Best practices

Summary