> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure and Explore JCasC > Guide to Jenkins Configuration as Code plugin, exporting and managing Jenkins configuration via declarative YAML for reproducible, version controlled setups, including installation, locations, validation, and best practices. 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/](https://plugins.jenkins.io/configuration-as-code/) * Examples & repo: [https://github.com/jenkinsci/configuration-as-code-plugin](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): ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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): ```yaml theme={null} 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: ```bash theme={null} # 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): ```yaml theme={null} systemMessage: "Loading data from Jenkins JCasC" ``` Apply the configuration from Manage Jenkins → Configuration as Code: 1. 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. 2. Click "Apply new configuration." The plugin will validate the YAML first. 3. If the YAML is valid the plugin will report success and show the timestamp when it was loaded. 4. 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: ```json theme={null} { "$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/](https://plugins.jenkins.io/configuration-as-code/) * JCasC GitHub repository and examples: [https://github.com/jenkinsci/configuration-as-code-plugin](https://github.com/jenkinsci/configuration-as-code-plugin) * Jenkins documentation: [https://www.jenkins.io/doc/](https://www.jenkins.io/doc/)