Skip to content

Configuration Reference

Files in this repo

File Committed Purpose
Dockerfile Yes Builds the Jenkins controller image with all plugins
docker-compose.yml Yes Runs the controller; mounts volumes and socket
casc.yml Yes Full Jenkins configuration as code — loaded at startup
.env.example Yes Template for required environment variables
.env No Your actual secrets — never commit
github-app.pem No Jenkins CI App private key — never commit
docs/ Yes This documentation

Environment variables (.env)

Variable Required Description
JENKINS_ADMIN_PASSWORD Yes Password for the local admin break-glass account
JENKINS_URL Yes Full public URL with no trailing slash — used by casc.yml for webhook and OAuth URLs
JENKINS_TEST_URL No Public URL for the test Jenkins instance — used by doc validation pipeline
GITHUB_USERNAME Yes Your GitHub username — used in shared library URL
GITHUB_ADMIN_USERNAME Yes GitHub username granted the admin role in Jenkins
GITHUB_ORG Yes GitHub org (or username for personal accounts) granted the developer role
GITHUB_APP_ID Yes Numeric App ID from your Jenkins CI App settings
GITHUB_WEBHOOK_SECRET Yes Random secret matching the value set in Jenkins CI App settings — verifies webhook signatures
GITHUB_OAUTH_CLIENT_ID Yes Client ID from your Jenkins Login App
GITHUB_OAUTH_CLIENT_SECRET Yes Client Secret from your Jenkins Login App

casc.yml sections

jenkins.securityRealm

Configures GitHub OAuth for user login. Reads GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET from the environment. The oauthScopes value read:org,user:email gives Jenkins enough access to identify the user and their org memberships.

jenkins.authorizationStrategy

Role Strategy with three roles:

Role Assigned to Permissions
admin GITHUB_ADMIN_USERNAME Full — Overall/Administer
developer GITHUB_ORG members only Build, read logs, cancel, replay
viewer (unassigned — add GitHub usernames here) Read-only

To add a collaborator as a developer, add their GitHub username to the developer role's assignments list in casc.yml and restart Jenkins (or reload JCasC via Manage Jenkins → Configuration as Code → Reload). For personal accounts set GITHUB_ORG to your GitHub username.

jenkins.clouds

Defines Docker build agent templates — one per language. All share the same Docker socket, remote FS path, and instance cap of 4 concurrent containers.

Label Image Language
python-3.14 python:3.14 Python
node-20 node:20 Node.js / JavaScript
java-21 maven:3.9-eclipse-temurin-21 Java (Maven)
go-1.22 golang:1.22 Go
dotnet-8 mcr.microsoft.com/dotnet/sdk:8.0 C# / .NET
ruby-3.3 ruby:3.3 Ruby

To add a new language: add a template block here with a new labelString and image, then restart Jenkins. Project Jenkinsfiles reference the label via agent { label 'node-20' } or specify the image directly with agent { docker { image 'node:20' } }.

credentials

Single gitHubApp credential with ID jenkins-ci-app. Used by: - GitHub Branch Source plugin (repo discovery, webhooks, build status) - Pipeline stages that push to GitHub (mkdocs gh-deploy, changelog commit) - Shared library retriever (clones jenkins-shared-library)

The private key is read from /run/secrets/github-app.pem inside the container using JCasC's ${readFile:...} syntax, avoiding multiline env var issues.

unclassified.location

Sets Jenkins' own public URL from JENKINS_URL. Required for: - GitHub webhook URL self-registration - OAuth callback construction - Build badge URLs

unclassified.globalLibraries

Registers the jenkins-shared-library repo as a shared pipeline library named shared. Project Jenkinsfiles load it with @Library('shared') _. Uses the jenkins-ci-app credential to clone the library repo.

docker-compose.yml volumes

Mount Purpose
jenkins_home:/var/jenkins_home Persists all Jenkins data — jobs, build history, plugins — across container rebuilds
/var/run/docker.sock:/var/run/docker.sock Gives Jenkins access to Docker Desktop daemon for spawning build agent containers
./casc.yml:/var/jenkins_home/casc_configs/casc.yml Injects the JCasC config file into the container at the path Jenkins watches
./github-app.pem:/run/secrets/github-app.pem:ro Mounts the private key read-only; path referenced in casc.yml via ${readFile:...}

Plugins installed

Plugin Purpose
git Git SCM support
pipeline-model-definition Declarative Pipeline syntax
github GitHub integration (webhooks, status)
credentials-binding withCredentials in pipelines
junit Test result trend graphs
docker-workflow docker { image '...' } agent blocks
ws-cleanup cleanWs() post-build workspace cleanup
github-branch-source GitHub Organization Folder — auto-discovers repos
cloudbees-folder Folder-scoped credentials per project
configuration-as-code JCasC — loads casc.yml at startup
github-oauth GitHub OAuth login for Jenkins UI
role-strategy Role-based access control