Skip to content

Jenkins CI Apps Setup

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

App type Purpose Used by
Jenkins CI App Jenkins reads repos, posts build status, auto-manages webhooks Jenkins CI pipeline
Jenkins Login App Jenkins login via GitHub account Humans logging into Jenkins UI

Part 1 — Jenkins CI App (CI/CD)

Create the app

  1. Go to GitHub → Settings → Developer settings → Jenkins CI Apps → New Jenkins CI 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 a strong random string (openssl rand -hex 32) and enter it here — Jenkins uses it to verify webhook signatures. Add the same value to .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. Set Subscribe to events:
  2. Push

  3. Pull request

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

  5. Click Create Jenkins CI App

Get the App ID

Note the App ID 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/jenkins-config/github-app.pem

github-app.pem is gitignored. Never commit it.

Install the app

  1. In the app settings, click Install App
  2. Select your account (<your-github-username>)
  3. Choose All repositories — this covers every current and future repo automatically

Part 2 — Jenkins Login App (user login)

Create the app

  1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
  2. Fill in:
  3. Application name: Jenkins CI 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 Where to put it
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 Jenkins CI App settings field
Jenkins CI App — webhook secret Jenkins CI 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.