Skip to main content
Managing Jenkins through its UI can be time-consuming and error-prone. The Configuration as Code (JCasC) plugin enables you to define your entire Jenkins setup using human-readable YAML files. In this guide, you’ll learn how to install the plugin, inspect your current configuration, and apply updates—all in a reproducible way.

​
Why Use Jenkins Configuration as Code?

  • Automate Jenkins setup and reduce manual steps
  • Store your Jenkins configuration in version control
  • Easily replicate environments across teams or clusters

​
1. Install the Configuration as Code Plugin

  1. Navigate to Manage Jenkins → Manage Plugins.
  2. Under the Available tab, search for Configuration as Code.
  3. Select the plugin, click Install without restart, then restart Jenkins when prompted.
  4. Log back in and verify the plugin is active.
Once installed, open Manage Jenkins → Configuration as Code. You will see options to replace, reload, download, or view your YAML configuration.
The image shows a Jenkins “Configuration as Code” interface, where users can replace configuration sources and perform actions like reloading, downloading, or viewing configurations. There is a warning about the export not being directly usable for a Jenkins YAML configuration.

​
2. Exploring Your Current Configuration

Click View Configuration to export the entire Jenkins setup in YAML format. This includes credentials, tool installations, security settings, and more. 
# System credentials example
credentials:
  system:
    domainCredentials:
      - usernamePassword:
          id: "gitea-server-creds"
          description: "Gitea Server Credentials"
          username: "gitea-admin"
          password: "{AAABAAAAAQ4e7wFYLRuoyZLN9NsLqahoKhKpJfItDGTyKusxQCu}"
          scope: GLOBAL

# Maven and Node.js tool installations
maven:
  installations:
    - name: "M3"
      properties:
        - installSource:
            installers:
              - maven:
                  id: "3.9.8"

nodejs:
  installations:
    - name: "nodejs-22-6-0"
      properties:
        - installSource:
            installers:
              - nodeJSInstaller:
                  id: "22.6.0"
      npmPackagesRefreshHours: 72

# Remoting security and welcome message
remotingSecurity:
  enabled: true
  slaveAgentPort: 0
  systemMessage: "Welcome to our Jenkins CI Controller"
The exported YAML may contain sensitive data (credentials, tokens). Secure it appropriately in your version control or store it behind an access-controlled vault.
For a complete reference, visit the Jenkins Configuration as Code plugin on GitHub.

​
3. Editing and Applying Your YAML Configuration

Store your YAML file on the Jenkins controller. For example: 
cd /var/lib/jenkins/JENKINS_BACKUP
vi jenkins-casc.yaml
Here’s a sample configuration that updates the system message and defines a custom view: 
remotingSecurity:
  enabled: true
  slaveAgentPort: 0
  systemMessage: |
    <h2>Maintenance Notice</h2>
    <ul>
      <li>Every Sunday at 11:45 PM ET</li>
      <li>Contact <a href="mailto:[email protected]">[email protected]</a></li>
    </ul>

updateCenter:
  sites:
    - id: "default"
      url: "https://updates.jenkins.io/update-center.json"

views:
  - name: "Build Monitor"
    config:
      displayBadgesFrom: "getLastBuild"
    jobNames:
      - "ascii-build-job"
      - "ascii-test-job"
  1. Save the file (jenkins-casc.yaml).
  2. Go to Manage Jenkins → Configuration as Code, set Path to /var/lib/jenkins/JENKINS_BACKUP/jenkins-casc.yaml.
  3. Click Apply New Configuration. Jenkins will validate the YAML and reload the setup automatically.
Ensure the YAML file is owned by the Jenkins user and has correct permissions (chmod 600) to prevent unauthorized access.

​
4. Configuration Actions

On the Configuration as Code page, you can perform the following actions:
ActionDescription
ReplaceLoad configuration from a local file or Git repository
ReloadRe-apply the last loaded YAML without specifying a new file
DownloadExport the current Jenkins configuration as a YAML file
ViewDisplay the full Jenkins configuration in YAML format
After applying changes, you can verify your jobs and views on the Jenkins dashboard.
The image shows a Jenkins dashboard displaying a list of build jobs with their statuses, last success, last failure, and duration. The interface includes options for managing Jenkins and viewing build history.

​
Sample JSON Schema Snippet

Use the JSON Schema for YAML validation or to generate documentation: 
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Jenkins Configuration as Code",
  "type": "object",
  "properties": {
    "remotingSecurity": {
      "type": "object",
      "properties": {
        "enabled": { "type": "boolean" },
        "slaveAgentPort": { "type": "integer" },
        "systemMessage": { "type": "string" }
      }
    }
  }
}
The image shows a Jenkins “Configuration as Code” interface, displaying options to replace, reload, download, or view configuration, with a warning about export limitations.

​
Resources and References

Watch Video