Jenkins as Code
Manage Jenkins configurations using code for automation and consistency.
Jenkins Configuration as Code
With the Configuration as Code plugin, you can easily reinstall or recreate your Jenkins server
at any time. All settings and jobs are defined in code, making the setup process fast, repeatable, and consistent.
Plugins
To start configuring your Jenkins instance with code, you first need to install the required plugin.
For this example, we'll use docker
since it's straightforward to set up and use.
In the installation process, I show you how to set up Jenkins using a docker-compose.yml
file. We will also use a Dockerfile
for easier management and customization.
# Jenkins image
FROM jenkins/jenkins:latest
USER root
# Don't use the Setup Wizard
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
# Remove every plugins
RUN rm -rf /var/jenkins_home/plugins/*
# Install Plugins
RUN jenkins-plugin-cli --plugins \
configuration-as-code:latest
USER jenkins
Authentication
Next, let's create the actual Jenkins configuration. We'll start by defining an Admin user for authentication.
To set up Jenkins Configuration as Code, follow these steps in order:
Create the following directory structure on your host machine:
.
├── Dockerfile
├── docker-compose.yml
└── jenkins
└── casc.yml
Write your Jenkins configuration in jenkins/casc.yml
. For example, to create an admin user:
jenkins:
securityRealm:
local:
allowsSignup: false
users:
- id: "admin"
password: "admin"
allowsSignup
: Disables user registration.
Build and start Jenkins using Docker Compose:
docker-compose up --build
Jenkins will now start with your configuration automatically applied.
You can check by going to http://localhost:8080
.
Jenkins is now fully configured using code !
Permissions
Now we need to install a new plugin to manage permissions.
Install the role-strategy
plugin to enable advanced permission management in Jenkins.
# Jenkins image
FROM jenkins/jenkins:latest
USER root
# Don't use the Setup Wizard
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
# Remove every plugins
RUN rm -rf /var/jenkins_home/plugins/*
# Install Plugins
RUN jenkins-plugin-cli --plugins \
configuration-as-code:latest \
role-strategy:latest
USER jenkins
Now that the plugin for permission management is installed, we can start creating roles.
We can now modify the casc.yml
file to add permission management.
jenkins:
securityRealm:
local:
allowsSignup: false
users:
- id: "admin"
password: "admin"
authorizationStrategy:
roleBased:
roles:
global:
- entries:
- user: "admin"
name: "Admin"
pattern: ".*"
description: "Administrator"
permissions:
- "Overall/Administer"
roles
: Group permissions under role names (e.g., Admin, ReadOnly).entries
: Specify which users or groups are assigned to each role.permissions
: List the specific actions that users in a role are allowed to perform (e.g.,Overall/Administer
,Job/Read
,View/Read
).
In the example above, the admin user is assigned to the Admin
role, granting them full administrative access to Jenkins.
You can create additional roles with more limited permissions and assign users as needed for fine-grained access control.
Jobs
You can define Jenkins jobs using Groovy scripts with the Job DSL
plugin. This allows you to manage jobs as code.
Plugin Installation
First, install the job-dsl
plugin by adding it to your Dockerfile:
# Jenkins image
FROM jenkins/jenkins:latest
USER root
# Don't use the Setup Wizard
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
# Remove every plugins
RUN rm -rf /var/jenkins_home/plugins/*
# Install Plugins
RUN jenkins-plugin-cli --plugins \
configuration-as-code:latest \
role-strategy:latest \
job-dsl:latest
USER jenkins
Jenkins Project
Let's define a Jenkins Job using a Groovy script. This makes your job configuration easy to version and automate.
Create the following directory structure on your host machine:
.
├── Dockerfile
├── docker-compose.yml
└── jenkins
├── casc.yml
└── job_dsl.groovy
Add your job definition to jenkins/job_dsl.groovy
. For example, to create a job that prints Hello from Job DSL!
:
job('example-job') {
description('A simple freestyle Jenkins job created via Job DSL.')
scm {
git('https://github.com/example/repo.git')
}
triggers {
scm('H/5 * * * *')
}
steps {
shell('echo "Hello from Job DSL!"')
}
}
scm
: Configures the source code management for the job. In this example, it uses aGit
repository as the source.triggers
: Sets up automatic triggers for the job. Here, the job is triggered bySCM
changes every 5 minutes.steps
: Defines the build steps to execute. In this case, it runs a shell command that prints a message.
This Groovy script, when used with the Job DSL plugin, will automatically create and configure the Jenkins job as described.
Now we need to instruct Jenkins to use this Groovy
script. To do this, add the following section to your casc.yml
:
jenkins:
securityRealm:
local:
allowsSignup: false
users:
- id: "admin"
password: "admin"
authorizationStrategy:
roleBased:
roles:
global:
- entries:
- user: "admin"
name: "Admin"
pattern: ".*"
description: "Administrator"
permissions:
- "Overall/Administer"
jobs:
- file: /var/jenkins_home/job_dsl.groovy
Now, update your docker-compose.yml
file to mount the Groovy job definition into the Jenkins container:
---
services:
jenkins:
container_name: jenkins
build: ./
image: jenkins:jcasc
ports:
- "8080:8080"
restart: unless-stopped
volumes:
- jenkins-data:/var/jenkins_home
# The path to your configuration file on your hosts
- ./jenkins/casc.yml:/var/jenkins_home/casc_configs/casc.yaml:ro
- ./jenkins/job_dsl.groovy:/var/jenkins_home/job_dsl.groovy:ro
environment:
CASC_JENKINS_CONFIG: "/var/jenkins_home/casc_configs"
entrypoint:
- "/usr/bin/tini"
- "--"
- "/usr/local/bin/jenkins.sh"
volumes:
jenkins-data: {}
You made your first job !
Pipeline
You can also define Jenkins Pipelines as code to automate complex workflows and CI/CD
processes.
Plugin Installation
First, install the workflow-aggregator
plugin by adding it to your Dockerfile:
# Jenkins image
FROM jenkins/jenkins:latest
USER root
# Don't use the Setup Wizard
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
# Remove every plugins
RUN rm -rf /var/jenkins_home/plugins/*
# Install Plugins
RUN jenkins-plugin-cli --plugins \
configuration-as-code:latest \
role-strategy:latest \
job-dsl:latest \
workflow-aggregator:latest
USER jenkins
Jenkins Pipeline
Let's define a Jenkins Pipeline Job using a Groovy script. Pipeline jobs let you describe your build and deploy process as code.
If you did not follow the first step, create this directory structure on your host machine:
.
├── Dockerfile
├── docker-compose.yml
└── jenkins
├── casc.yml
└── job_dsl.groovy
Add your pipeline job definition to jenkins/job_dsl.groovy
. For example, to create a pipeline job that prints Hello from Jenkins Pipeline!
:
pipelineJob('example-pipeline') {
description('A simple Jenkins Pipeline job created via Job DSL.')
definition {
cps {
script("""
pipeline {
agent any
stages {
stage('Hello') {
steps {
echo 'Hello from Jenkins Pipeline!'
}
}
}
}
""".stripIndent())
sandbox(true)
}
}
}
definition
: Defines the pipeline using the CPS (scripted pipeline) DSL.script
: Contains the Groovy pipeline script. In this example:agent any
: Runs the pipeline on any available Jenkins agent.sandbox(true)
: Executes the pipeline script in a secure Groovy sandbox environment.
This structure makes your pipeline job clear, maintainable, and secure.
This Groovy script, when used with the Job DSL plugin, will automatically create and configure the Jenkins Pipeline as described.
You made your first Pipeline !