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	Rich test result reporting and trend history
`observability`	+ Loki, Fluent Bit, Grafana	Centralised log aggregation and dashboards (Phase 5)
`ai`	+ Neo4j, Knowledge API	Knowledge graph and LLM integration (Phase 7)
`full`	Everything above	All platform features

# Start with all reporting features enabled — add to .env before docker compose up
COMPOSE_PROFILES=reporting

The full profile automatically includes any new profiles added in future phases.

Environment variables¶

Every variable is documented in .env.example with a comment explaining its purpose, valid values, and when to change it. The tables below are a reference summary.

Core — Jenkins¶

Variable	Required	Default	Description
`JENKINS_ADMIN_PASSWORD`	Yes	—	Break-glass admin account password — bypasses OAuth for emergency recovery
`JENKINS_URL`	Yes	—	Public URL with 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 from the repo
`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 tunnel that exposes Jenkins to the internet — generate at 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 Jenkins CI 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 — see trust level table below
`JENKINS_FOLDER_SCAN_INTERVAL`	No	`H/5 * * * *`	Cron schedule for org rescan — fallback when webhooks fail during tunnel downtime

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	Not recommended — 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

The Allure UI is accessible at:

http://localhost:5050/allure-docker-service/projects/default/reports/latest/index.html

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`	Storage 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`	Issue tracker 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`	Number of 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¶

All AI features are disabled by default. You are responsible for what data your chosen provider receives.

Variable	Required	Default	Description
`AI_ENABLED`	No	`false`	Master switch — set to `true` to enable all AI features
`LLM_PROVIDER`	No	—	Provider — `anthropic`, `openai`, `azure-openai`, `gemini`, `bedrock`, `ollama`, `openai-compatible`
`LLM_API_KEY`	No	—	API key for the provider — 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`¶

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	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 JCasC via Manage Jenkins → Configuration as Code → Reload. For personal repos set GITHUB_ORG to your GitHub username.

`jenkins.clouds`¶

Defines Docker build agent templates — one per language. All share the same Docker socket and remote filesystem path. The instance cap per agent 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 new language: add a template block to casc.yml with a new labelString and image, then restart Jenkins. Project Jenkinsfiles reference the label via agent { label '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 environment variable issues.

`unclassified.location`¶

Sets Jenkins' own public URL from JENKINS_URL. Required for GitHub webhook URL self-registration, OAuth callback construction, and 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') _. Currently pinned to main — will be updated to a release tag in Phase 2.

`docker-compose.yml` 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 posted by pipelines after each build	Destroyed by `down -v`
`allure_reports`	Rendered HTML reports and trend history graphs	Destroyed by `down -v`

Warning: docker compose down -v permanently destroys all three volumes. Allure trend history is lost unless you have configured publishArtifacts() with an external artifact backend. Always run 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¶

A minimal working .env for a personal GitHub account with Allure reporting enabled:

# ── Compose profiles ────────────────────────────────────────────────────────
# Start Jenkins, Cloudflare tunnel, and Allure test reporting
COMPOSE_PROFILES=reporting

# ── Jenkins ─────────────────────────────────────────────────────────────────
# Strong random password — store somewhere safe for emergency break-glass access
JENKINS_ADMIN_PASSWORD=correct-horse-battery-staple
JENKINS_URL=https://jenkins.example.com

# ── Cloudflare tunnel ───────────────────────────────────────────────────────
# Token generated in the Cloudflare One dashboard under Networks → Tunnels
CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjMTIzNDU2Nzg5...

# ── GitHub identity ──────────────────────────────────────────────────────────
# For personal accounts, GITHUB_ORG matches your username
GITHUB_USERNAME=tacobort
GITHUB_ADMIN_USERNAME=tacobort
GITHUB_ORG=tacobort

# ── Jenkins CI App ───────────────────────────────────────────────────────────
# App ID shown on the GitHub App settings page
GITHUB_APP_ID=123456
# Random string — must match the webhook secret entered in GitHub App settings
GITHUB_WEBHOOK_SECRET=a7f3d9e2c8b1...

# ── Jenkins Login App (OAuth) ────────────────────────────────────────────────
GITHUB_OAUTH_CLIENT_ID=Iv1.abc123def456
GITHUB_OAUTH_CLIENT_SECRET=abcdef1234567890abcdef1234567890abcdef12

# ── Fork PR trust ────────────────────────────────────────────────────────────
# Add contributors as GitHub repo collaborators, then their PRs run automatically
JENKINS_FORK_PR_TRUST=collaborators

# ── Allure ───────────────────────────────────────────────────────────────────
# Keep 30 builds of history in trend graphs — increase for longer trend visibility
ALLURE_HISTORY_LIMIT=30