Quick Deploy¶

Deploy Jenkins from scratch in under 30 minutes.

Prerequisites¶

Docker Desktop installed and running
Git and GitHub CLI (gh) installed
A GitHub account (<your-github-username>)
A domain managed by Cloudflare (or use a temporary tunnel for testing)

Step 1 — Clone this repo¶

git clone https://github.com/<your-github-username>/jenkins-config.git
cd jenkins-config

Step 2 — Set up Cloudflare Tunnel¶

Jenkins needs a public URL for GitHub webhooks and OAuth callbacks. Do this before creating the Jenkins CI Apps so you have the URL ready.

Full instructions: docs/cloudflare.md

Output: a stable public URL, e.g. https://jenkins.yourdomain.com

Step 3 — Create Jenkins CI Apps¶

You need two separate Jenkins CI Apps:

App	Purpose	What you get
Jenkins CI App	Jenkins reads repos, posts build status, manages webhooks	App ID + private key `.pem`
Jenkins Login App	Jenkins user login via GitHub account	Client ID + Client Secret

Full instructions: docs/github-apps.md

Step 4 — Configure `.env`¶

cp .env.example .env

Open .env and fill in every value:

JENKINS_ADMIN_PASSWORD=<strong-password>
JENKINS_URL=https://jenkins.yourdomain.com

GITHUB_APP_ID=<from Step 3>
GITHUB_OAUTH_CLIENT_ID=<from Step 3>
GITHUB_OAUTH_CLIENT_SECRET=<from Step 3>

Step 5 — Add the Jenkins CI App private key¶

Copy the .pem file downloaded during Jenkins CI App creation into the repo root:

WindowsmacOS / Linux

cp $env:USERPROFILE\Downloads\your-app-name.pem github-app.pem

cp ~/Downloads/your-app-name.pem github-app.pem

github-app.pem is gitignored and never committed.

Step 6 — Build and start Jenkins¶

docker compose up --build -d

First build takes a few minutes — it installs all plugins. Subsequent starts are fast.

Verify Jenkins is running:

docker compose logs -f jenkins

Wait for Jenkins is fully up and running in the logs.

Step 7 — Log in¶

Open http://localhost:8080 (or your public Cloudflare URL).

Log in with your GitHub account via the GitHub OAuth button. Your <your-github-username> account is pre-configured as admin via casc.yml.

Step 8 — Create the GitHub Organization Folder job¶

This is a one-time manual step that auto-discovers all your repos.

New Item → name it <your-github-username> → select GitHub Organization
Credentials: select jenkins-ci-app
Owner: <your-github-username>
Behaviors: leave defaults (discovers branches and PRs)
Fork PR trust (security-critical): In Behaviors → Discover fork pull requests → set Trust to Contributors — fork PR builds only run if the author has a previously merged PR. Set to Nobody for maximum security (all fork PRs require manual approval).
Save — Jenkins scans your account and creates a job for every repo containing a Jenkinsfile

From this point, any new repo with a Jenkinsfile is picked up automatically within minutes of the next push.

Step 9 — Verify¶

Push a commit to any repo that has a Jenkinsfile. You should see: - A build appear in Jenkins within seconds (via webhook) - Build status posted back to the GitHub commit/PR

Updating Jenkins¶

To apply config changes (plugins, casc.yml, Dockerfile):

git pull
docker compose up --build -d

Jenkins reloads JCasC config automatically on restart without losing build history (stored in the jenkins_home volume).

Teardown¶

Stop Jenkins without losing data:

docker compose down

Full wipe including all build history:

docker compose down -v