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 |
+ 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 the 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). Also used by the knowledge-api POST /api/v1/query/prompt endpoint; defaults to gpt-4o-mini when unset. |
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) |
| Knowledge API | 0.5 | 1 GB (Phase 7) |
| 4 × agents (peak) | 4.0 | 4 GB |
| Total (full + 4 agents) | ~7.5 | ~7.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