Skip to content

GitHub Apps Setup

Two separate GitHub Apps are required. They serve different purposes and must be created independently.

App Purpose Used by
Jenkins CI App Reads repos, posts build status, manages webhooks Jenkins CI pipeline
Jenkins Login App GitHub OAuth login for the Jenkins UI Humans logging into Jenkins

Part 1 — Jenkins CI App

Create the app

  1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
  2. Fill in:
  3. Name: <your-github-username>-jenkins (or any unique name)
  4. Homepage URL: your JENKINS_URL (e.g. https://jenkins.yourdomain.com)
  5. Webhook URL: https://jenkins.yourdomain.com/github-webhook/

  6. Webhook secret: generate with openssl rand -hex 32 — same value goes in .env as GITHUB_WEBHOOK_SECRET

  7. Set Repository permissions:

Permission Access
Contents Read
Metadata Read (mandatory)
Pull requests Read
Commit statuses Read & Write
Checks Read & Write
Webhooks Read & Write

  1. Subscribe to events: Push, Pull request

  2. Where can this app be installed: Only on this account

  3. Click Create GitHub App

Get the App ID

The App ID is shown at the top of the app settings page. Add it to .env:

GITHUB_APP_ID=123456

Generate the private key

Scroll to the bottom of the app settings page → Generate a private key

A .pem file downloads automatically. Copy it to the repo root:

cp $env:USERPROFILE\Downloads\<your-github-username>-jenkins.pem .\github-app.pem

cp ~/Downloads/<your-github-username>-jenkins.pem /path/to/magi/github-app.pem

Never commit this file

github-app.pem is gitignored. It is mounted read-only into the container and never leaves the host. Anyone with this key can authenticate as your Jenkins CI App.

Install the app

  1. In the app settings, click Install App
  2. Select your account
  3. Choose All repositories — covers every current and future repo automatically

Part 2 — Jenkins Login App (OAuth)

Create the app

  1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
  2. Fill in:
  3. Application name: Jenkins Login
  4. Homepage URL: your JENKINS_URL

  5. Authorization callback URL: https://jenkins.yourdomain.com/securityRealm/finishLogin

  6. Click Register application

Get credentials

On the next page:

  • Note the Client ID → add to .env as GITHUB_OAUTH_CLIENT_ID
  • Click Generate a new client secret → add to .env as GITHUB_OAUTH_CLIENT_SECRET
GITHUB_OAUTH_CLIENT_ID=abc123
GITHUB_OAUTH_CLIENT_SECRET=def456...

Summary — what goes where

Value Destination
Jenkins CI App — App ID .env → GITHUB_APP_ID
Jenkins CI App — private key github-app.pem in repo root
Jenkins CI App — webhook URL GitHub App settings field
Jenkins CI App — webhook secret GitHub App settings field + .env → GITHUB_WEBHOOK_SECRET
OAuth App — Client ID .env → GITHUB_OAUTH_CLIENT_ID
OAuth App — Client Secret .env → GITHUB_OAUTH_CLIENT_SECRET
OAuth App — callback URL OAuth App settings field

Updating the webhook URL

If your Cloudflare Tunnel URL changes, update it in two places:

  1. Jenkins CI App settings → Webhook URL
  2. Jenkins Login App settings → Authorization callback URL

Then update JENKINS_URL in .env and restart Jenkins.