Jenkins configuration as code (JCasC) - Commands & Configuration

Introduction

Jenkins configuration as code lets you set up Jenkins automatically using a file. This solves the problem of manually clicking through settings every time you install Jenkins or want to share your setup.

When you want to quickly recreate the same Jenkins setup on a new server without manual steps

When you want to keep your Jenkins settings in version control to track changes

When you want to automate Jenkins setup as part of your infrastructure deployment

When you want to share your Jenkins configuration with your team easily

When you want to avoid mistakes from manual configuration by using a single source of truth

Config File - jenkins.yaml

jenkins.yaml

jenkins:
  systemMessage: "Welcome to Jenkins configured as code!"
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin123"
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false
  tools:
    git:
      installations:
        - name: "Default"
          home: "/usr/bin/git"
  nodes:
    - permanent:
        name: "built-in"
        remoteFS: "/var/jenkins_home"
        labelString: "master"
        launcher:
          jnlp:
            workDirSettings:
              disabled: false
              internalDir: "remoting"
              failIfWorkDirIsMissing: false

This YAML file sets Jenkins configuration as code.

• systemMessage: Shows a welcome message on Jenkins dashboard.
• securityRealm: Defines user login settings with one admin user.
• authorizationStrategy: Allows logged-in users full access, no anonymous read.
• tools: Configures Git tool location.
• nodes: Defines the built-in Jenkins node with JNLP launcher.

Commands

Starts Jenkins server on port 8080 with admin user and disables setup wizard for automation.

Terminal

java -jar jenkins.war --httpPort=8080 --argumentsRealm.passwd.admin=admin123 --argumentsRealm.roles.admin=admin -Djenkins.install.runSetupWizard=false

Expected Output

Running from: /home/user/jenkins.war

2024-06-01 12:00:00.000+0000 [id=1]    INFO    org.eclipse.jetty.server.Server#main: Started @12345ms

2024-06-01 12:00:01.000+0000 [id=1]    INFO    hudson.WebAppMain#contextInitialized: Jenkins is fully up and running

→

--httpPort=8080 - Sets Jenkins to listen on port 8080

→

--argumentsRealm.passwd.admin=admin123 - Creates admin user with password

→

-Djenkins.install.runSetupWizard=false - Skips initial setup wizard

Applies the Jenkins configuration as code from the jenkins.yaml file to set up Jenkins automatically.

Terminal

curl -X POST -H "Content-Type: application/yaml" --data-binary @jenkins.yaml http://localhost:8080/configuration-as-code/apply

Expected Output

{"status":"success","message":"Configuration applied successfully"}

→

-X POST - Sends data to Jenkins to apply configuration

→

-H "Content-Type: application/yaml" - Specifies the data format as YAML

→

--data-binary @jenkins.yaml - Uploads the YAML configuration file

Exports the current Jenkins configuration as YAML to verify what is set.

Terminal

curl http://localhost:8080/configuration-as-code/export

Expected Output

jenkins:

  systemMessage: "Welcome to Jenkins configured as code!"

  securityRealm:

    local:

      allowsSignup: false

      users:

        - id: "admin"

          password: "admin123"

  authorizationStrategy:

    loggedInUsersCanDoAnything:

      allowAnonymousRead: false

  tools:

    git:

      installations:

        - name: "Default"

          home: "/usr/bin/git"

  nodes:

    - permanent:

        name: "built-in"

        remoteFS: "/var/jenkins_home"

        labelString: "master"

        launcher:

          jnlp:

            workDirSettings:

              disabled: false

              internalDir: "remoting"

              failIfWorkDirIsMissing: false

Key Concept

If you remember nothing else from this pattern, remember: Jenkins configuration as code lets you automate and version control your Jenkins setup using a simple YAML file.

Common Mistakes

Trying to apply JCasC configuration before Jenkins is fully started

Jenkins rejects configuration changes if the server is not ready, causing errors.

Wait until Jenkins logs show it is fully up before applying the configuration.

Using incorrect YAML indentation or syntax in the jenkins.yaml file

YAML parsing fails and Jenkins cannot apply the configuration.

Use a YAML validator and follow exact indentation rules to ensure valid syntax.

Not disabling the setup wizard when automating Jenkins startup

The setup wizard blocks automated configuration and requires manual input.

Start Jenkins with -Djenkins.install.runSetupWizard=false to skip the wizard.

Summary

Start Jenkins with admin user and disable setup wizard for automation.

Create a jenkins.yaml file describing your Jenkins settings in YAML format.

Apply the configuration using Jenkins Configuration as Code REST API.

Verify the applied configuration by exporting it back as YAML.