Jenkins GitHub Integration: Webhooks and Triggers
Configure Jenkins to automatically build on every GitHub push using webhooks, with proper authentication, branch filtering, and commit status reporting back to pull requests. Done right, GitHub and Jenkins behave like one system — done wrong, you get builds that trigger on nothing or on everything.
Table of Contents
- How the Flow Works
- Two Ways to Trigger Builds
- Setup: GitHub Webhook
- Jenkins Configuration
- Jenkinsfile with Branch Filtering
- Private Repositories
- Troubleshooting
- Security Checklist
How the Flow Works
push/PR → GitHub → webhook POST → Jenkins /github-webhook/
→ multibranch scan → matching branch job → build
→ githubNotify → commit status (✓/✗) appears on the PR
Two directions of traffic: GitHub→Jenkins (webhooks that say "something changed") and Jenkins→GitHub (API calls that fetch code, update commit statuses, and read PR metadata). Both need credentials — the webhook needs a secret so only GitHub can trigger it, and the API calls need a token so Jenkins can read private repos and write statuses.
Two Ways to Trigger Builds
| Method | How | Pros | Cons |
|---|---|---|---|
| Polling | Jenkins asks GitHub every N minutes | Works behind firewalls | Delayed, wasteful |
| Webhooks | GitHub pushes an event to Jenkins | Instant builds | Jenkins must be reachable |
Webhooks are the standard for production — a push triggers a build in seconds. Polling is only for when Jenkins isn't publicly reachable — behind a corporate firewall with no inbound path, pollSCM is the fallback that still gets builds eventually.
Setup: GitHub Webhook
Step 1: Add the Webhook in GitHub
Repository → Settings → Webhooks → Add webhook:
- Payload URL:
https://jenkins.example.com/github-webhook/(trailing slash matters — Jenkins 404s without it) - Content type:
application/json - Events: "Just the push event" (or add
pull_requestfor PR builds) - Active: ✓
GitHub sends a test ping — a green checkmark means Jenkins received it. For a whole organization, configure the webhook at the org level once instead of per-repo.
Step 2: Securing the Webhook
Set a secret so only GitHub can trigger builds:
- Generate a secret:
openssl rand -hex 20 - Add it in the GitHub webhook Secret field
- Jenkins validates the
X-Hub-Signature-256header automatically when the GitHub plugin's shared secret matches.
Without the secret, anyone who finds your Jenkins URL can trigger builds — a public endpoint running arbitrary job triggers is not a thing you want.
Jenkins Configuration
Install Required Plugins
- GitHub Integration Plugin
- GitHub Branch Source Plugin (for multibranch)
- Pipeline plugin
Multibranch Pipeline (Recommended)
Multibranch pipelines auto-discover branches and PRs — the feature that makes Jenkins behave like modern hosted CI:
- New Item → Multibranch Pipeline
- Branch Sources → GitHub
- Add credentials + repository URL
- Behaviours: Discover branches + PRs
- Scan triggers: "Periodically if not otherwise run" as fallback (covers webhook misses)
Jenkins will find the Jenkinsfile in every branch and create jobs automatically — PRs get tested before merge, deleted branches get garbage-collected, and no one has to click "New Job" per feature.
Jenkinsfile with Branch Filtering
pipeline {
agent any
triggers {
// Backup polling — webhooks are primary
pollSCM('H/5 * * * *')
}
stages {
stage('Build') {
steps {
sh 'npm ci && npm run build'
}
}
stage('Test') {
steps {
sh 'npm test'
}
post {
always {
junit 'test-results/**/*.xml'
}
}
}
stage('Deploy to Staging') {
when { branch 'develop' }
steps {
sh './deploy.sh staging'
}
}
stage('Deploy to Production') {
when { branch 'main' }
input { message 'Deploy to production?' }
steps {
sh './deploy.sh production'
}
}
}
post {
success {
// Report build status back to GitHub
githubNotify status: 'SUCCESS',
context: 'ci/jenkins',
description: 'Build passed'
}
failure {
githubNotify status: 'FAILURE',
context: 'ci/jenkins',
description: 'Build failed'
}
}
}
githubNotify is what makes the integration feel complete — commit statuses show up on the PR as the familiar ✓/✗ next to the commit, so reviewers see CI results without leaving GitHub. Pair it with branch protection requiring the ci/jenkins check and merges gate on your pipeline.
Private Repositories
SSH Key Authentication
# Generate a deploy key
ssh-keygen -t ed25519 -C "jenkins@mycompany" -f jenkins_key
- Add the public key to GitHub repo → Settings → Deploy keys
- Add the private key to Jenkins credentials (SSH Username with private key)
- Use SSH URL:
git@github.com:org/repo.git
Deploy keys are scoped to one repo — the right blast radius. Don't reuse a personal SSH key or a machine user's key across repos.
GitHub App Authentication (Best for Orgs)
- Create a GitHub App in your org settings
- Grant Contents: Read, Metadata: Read, Commit Statuses: Write
- Install the app on your repositories
- Add App ID + private key to Jenkins → GitHub App credentials
Apps give finer permissions and better rate limits than PATs — and they don't die when the employee who created the PAT leaves. For anything beyond a handful of repos, this is the right answer.
Troubleshooting
Webhook shows ✓ but builds don't trigger
# Check Jenkins webhook logs
# Manage Jenkins → System Log → Add recorder for:
# com.cloudbees.jenkins.GitHubWebHook
Common causes:
- Job isn't multibranch or lacks GitHub trigger config
- Branch filter excludes the pushed branch
- Jenkins URL mismatch (GitHub delivers, Jenkins ignores)
"Invalid hook signature" errors
The secret in GitHub doesn't match Jenkins' GitHub plugin secret. Re-generate and update both sides — the signature check failing means one of them has the wrong value, and it's usually whichever one you set first.
Builds trigger on every push to every branch
// Restrict with when conditions
when {
anyOf {
branch 'main'
branch 'develop'
changeRequest() // PRs
}
}
Or filter in the multibranch job config: Behaviours → "Filter by name (regex)": main|develop|PR-.* — cheaper than letting every branch build and discarding most of them.
GitHub rate limiting
Symptoms: 403 rate limit exceeded in Jenkins logs.
Fix: authenticate all GitHub API calls — add credentials to the multibranch source, or use a GitHub App (much higher limits). Anonymous API access from a shared Jenkins IP hits the 60/hour cap fast.
Security Checklist
- Webhook secret configured
- Jenkins behind HTTPS (webhooks should never go over plain HTTP)
- Deploy keys scoped to single repos (not org-wide keys)
-
scriptApproval— review any pending script signatures - Don't log secrets: use
withCredentials, neverecho $SECRET
Related Articles
Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.