Configuration Reference¶
Files in this repo¶
| File | Committed | Purpose |
|---|---|---|
Dockerfile |
Yes | Builds the Jenkins controller image with all plugins |
docker-compose.yml |
Yes | Defines all platform services, profiles, volumes, and resource limits |
casc.yml |
Yes | Full Jenkins configuration as code — loaded at startup via JCasC |
.env.example |
Yes | Template for all environment variables — copy to .env to configure |
.env |
No | Your actual secrets — never commit |
github-app.pem |
No | Jenkins CI App private key — never commit |
docs/ |
Yes | This documentation |
Docker Compose profiles¶
Services are grouped into profiles. Core services start automatically with no profile flag.
Optional profiles are activated via COMPOSE_PROFILES in .env.
| Profile | Services included | Purpose |
|---|---|---|
| (none — core) | Jenkins, Cloudflare tunnel | Always on — CI pipeline execution |
reporting |
+ Allure | Test result reporting and trend history |
observability |
+ Loki, Fluent Bit, Grafana | Log aggregation and dashboards (Phase 5) |
ai |
+ Neo4j, Knowledge API | Knowledge graph and LLM integration (Phase 7) |
full |
Everything above | All platform features |
Environment variables¶
Every variable is documented in .env.example. The tables below are a reference summary.
Core — Jenkins¶
| Variable | Required | Default | Description |
|---|---|---|---|
JENKINS_ADMIN_PASSWORD |
Yes | — | Break-glass admin password — bypasses OAuth for emergency recovery |
JENKINS_URL |
Yes | — | Public URL, no trailing slash — used for OAuth callback and webhook registration |
JENKINS_TEST_URL |
No | http://jenkins:8080 |
Internal URL for smoke tests running inside the Docker network |
JENKINS_AGENT_INSTANCE_CAP |
No | 4 |
Maximum concurrent agent containers per agent type |
JENKINS_DEFAULT_AGENT |
No | — | Fallback agent label when detectAgent() cannot infer one |
JENKINS_CPU_LIMIT |
No | 1.0 |
CPU limit for the Jenkins controller container |
JENKINS_MEM_LIMIT |
No | 1g |
Memory limit for the Jenkins controller container |
Core — Cloudflare Tunnel¶
| Variable | Required | Default | Description |
|---|---|---|---|
CLOUDFLARE_TUNNEL_TOKEN |
Yes | — | Token for the Cloudflare Tunnel exposing Jenkins — generate in Cloudflare dashboard |
Core — GitHub¶
| Variable | Required | Default | Description |
|---|---|---|---|
GITHUB_USERNAME |
Yes | — | Your GitHub username — used in shared library URL |
GITHUB_ADMIN_USERNAME |
Yes | — | GitHub username granted the Jenkins admin role |
GITHUB_ORG |
Yes | — | GitHub org or username whose members get the developer role |
GITHUB_APP_ID |
Yes | — | Numeric App ID from Jenkins CI App settings |
GITHUB_WEBHOOK_SECRET |
Yes | — | Random secret matching the value set in the GitHub App webhook settings |
GITHUB_OAUTH_CLIENT_ID |
Yes | — | Client ID from Jenkins Login App |
GITHUB_OAUTH_CLIENT_SECRET |
Yes | — | Client Secret from Jenkins Login App |
JENKINS_FORK_PR_TRUST |
No | collaborators |
Controls which fork PRs trigger CI automatically |
JENKINS_FOLDER_SCAN_INTERVAL |
No | H/5 * * * * |
Cron schedule for org rescan — fallback when webhooks fail |
Fork PR trust levels:
| Value | Who triggers CI on fork PRs | Trade-off |
|---|---|---|
nobody |
No one — all require manual approval | Maximum security, maximum friction |
contributors |
Authors with a previously merged PR | Chicken-and-egg for first-time contributors |
collaborators |
Explicitly added repo collaborators | Recommended — deliberate per-person trust |
organization |
All GitHub org members | Good for trusted teams with org membership |
everyone |
Anyone | Do not use — pipelines have credential access |
Reporting — Allure¶
Requires COMPOSE_PROFILES to include reporting or full.
| Variable | Required | Default | Description |
|---|---|---|---|
ALLURE_PORT |
No | 5050 |
Port the Allure UI and API are accessible on |
ALLURE_HISTORY_LIMIT |
No | 20 |
Number of previous builds retained in trend history |
ALLURE_CPU_LIMIT |
No | 0.5 |
CPU limit for the Allure container |
ALLURE_MEM_LIMIT |
No | 512m |
Memory limit for the Allure container |
Agents¶
| Variable | Required | Default | Description |
|---|---|---|---|
AGENT_CPU_LIMIT |
No | 1.0 |
CPU limit per ephemeral agent container |
AGENT_MEM_LIMIT |
No | 1g |
Memory limit per ephemeral agent container |
Artifact Storage¶
| Variable | Required | Default | Description |
|---|---|---|---|
ARTIFACT_STORE_TYPE |
No | local |
Backend — local, s3, azure, gcs, nexus, artifactory |
ARTIFACT_STORE_URL |
No | — | Endpoint URL for the configured backend |
ARTIFACT_STORE_CREDENTIALS |
No | — | Jenkins credential ID for authenticating with the backend |
Issue Tracking¶
| Variable | Required | Default | Description |
|---|---|---|---|
ISSUE_TRACKER_TYPE |
No | github |
Adapter — github, jira, linear, plane, azure-devops |
ISSUE_TRACKER_URL |
No | — | Base URL for non-GitHub trackers |
ISSUE_TRACKER_API_KEY |
No | — | API key for the configured tracker |
ISSUE_TRACKER_PROJECT |
No | — | Project or board identifier within the tracker |
ISSUE_AUTO_CREATE |
No | false |
Auto-create an issue when a build fails N consecutive times |
ISSUE_AUTO_CREATE_THRESHOLD |
No | 3 |
Consecutive failures before auto-creating an issue |
SMART_COMMITS_ENABLED |
No | true |
Parse commit messages for issue references and update the tracker |
AI / LLM Integration¶
Disabled by default
All AI features are off until AI_ENABLED=true is set. You are responsible for what data
your chosen provider receives.
| Variable | Required | Default | Description |
|---|---|---|---|
AI_ENABLED |
No | false |
Master switch — enables all AI features |
LLM_PROVIDER |
No | — | anthropic, openai, azure-openai, gemini, bedrock, ollama, openai-compatible |
LLM_API_KEY |
No | — | API key — not required for Ollama |
LLM_BASE_URL |
No | — | Base URL — required for Ollama, Azure OpenAI, and compatible providers |
LLM_MODEL_FAST |
No | — | Model for high-volume simple tasks (failure analysis, security explanation) |
LLM_MODEL_STANDARD |
No | — | Model for medium tasks (PR review, changelog summarisation) |
LLM_MODEL_POWERFUL |
No | — | Model for complex tasks (chatbot, test generation) |
Resource limits at peak load¶
With COMPOSE_PROFILES=full and JENKINS_AGENT_INSTANCE_CAP=4:
| Service | CPU | RAM |
|---|---|---|
| Jenkins controller | 1.0 | 1 GB |
| Cloudflare tunnel | 0.25 | 128 MB |
| Allure | 0.5 | 512 MB |
| Loki | 0.5 | 512 MB (Phase 5) |
| Fluent Bit | 0.25 | 128 MB (Phase 5) |
| Grafana | 0.5 | 512 MB (Phase 5) |
| Neo4j | 1.0 | 2 GB (Phase 7) |
| Knowledge API | 0.5 | 512 MB (Phase 7) |
| 4 × agents (peak) | 4.0 | 4 GB |
| Total (full + 4 agents) | ~8.5 | ~9.5 GB |
Ensure Docker Desktop has sufficient resources allocated under Settings → Resources.
casc.yml sections¶
jenkins.securityRealm¶
GitHub OAuth for user login. Reads GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET
from the environment. The read:org,user:email OAuth scope 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 |
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 reload via Manage Jenkins → Configuration as Code → Reload.
For personal repos, set GITHUB_ORG to your GitHub username.
jenkins.clouds¶
Docker build agent templates — one per language. All share the same Docker socket and remote
filesystem path. Instance cap per type is controlled by JENKINS_AGENT_INSTANCE_CAP (default: 4).
| 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 language: add a template block to casc.yml with a new labelString and image, then
restart Jenkins.
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 (
deployMkdocs, changelog commit) - Shared library retriever (clones
melchior)
The private key is read from /run/secrets/github-app.pem inside the container using JCasC's
${readFile:...} syntax, avoiding multiline environment variable issues.
unclassified.location¶
Sets Jenkins' own public URL from JENKINS_URL. Required for webhook URL self-registration,
OAuth callback construction, and build badge URLs.
unclassified.globalLibraries¶
Registers melchior as a shared pipeline library named shared. Jenkinsfiles load
it with @Library('shared') _. Currently pinned to main — will be updated to a release tag in Phase 2.
Volumes¶
| Volume | Purpose | Risk |
|---|---|---|
jenkins_home |
All Jenkins data — jobs, build history, plugins, credentials | Destroyed by down -v |
allure_results |
Raw JUnit/Allure XML files from each build | Destroyed by down -v |
allure_reports |
Rendered HTML reports and trend history graphs | Destroyed by down -v |
Volume destruction
docker compose down -v permanently destroys all three volumes. Allure trend history is
unrecoverable unless you have configured publishArtifacts() with an external backend.
Always use docker compose down (without -v) to stop the stack while preserving data.
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 with Jenkinsfiles |
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 |
Complete example configuration¶
Minimal working .env for a personal GitHub account with Allure reporting enabled:
# ── Compose profiles ──────────────────────────────────────────────────
COMPOSE_PROFILES=reporting
# ── Jenkins ───────────────────────────────────────────────────────────
JENKINS_ADMIN_PASSWORD=correct-horse-battery-staple
JENKINS_URL=https://jenkins.example.com
# ── Cloudflare tunnel ─────────────────────────────────────────────────
CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjMTIzNDU2Nzg5...
# ── GitHub identity ───────────────────────────────────────────────────
GITHUB_USERNAME=rtsko
GITHUB_ADMIN_USERNAME=rtsko
GITHUB_ORG=rtsko
# ── Jenkins CI App ────────────────────────────────────────────────────
GITHUB_APP_ID=123456
GITHUB_WEBHOOK_SECRET=a7f3d9e2c8b1...
# ── Jenkins Login App (OAuth) ─────────────────────────────────────────
GITHUB_OAUTH_CLIENT_ID=Iv1.abc123def456
GITHUB_OAUTH_CLIENT_SECRET=abcdef1234567890abcdef1234567890abcdef12
# ── Fork PR trust ─────────────────────────────────────────────────────
JENKINS_FORK_PR_TRUST=collaborators
# ── Allure ────────────────────────────────────────────────────────────
ALLURE_HISTORY_LIMIT=30