Jenkins

Jenkins GitHub Integration: Webhooks and Triggers

Intermediate
14 minutes
Updated October 2026

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

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

MethodHowProsCons
PollingJenkins asks GitHub every N minutesWorks behind firewallsDelayed, wasteful
WebhooksGitHub pushes an event to JenkinsInstant buildsJenkins 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_request for 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:

  1. Generate a secret: openssl rand -hex 20
  2. Add it in the GitHub webhook Secret field
  3. Jenkins validates the X-Hub-Signature-256 header 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 pipelines auto-discover branches and PRs — the feature that makes Jenkins behave like modern hosted CI:

  1. New Item → Multibranch Pipeline
  2. Branch Sources → GitHub
  3. Add credentials + repository URL
  4. Behaviours: Discover branches + PRs
  5. 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
  1. Add the public key to GitHub repo → Settings → Deploy keys
  2. Add the private key to Jenkins credentials (SSH Username with private key)
  3. 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)

  1. Create a GitHub App in your org settings
  2. Grant Contents: Read, Metadata: Read, Commit Statuses: Write
  3. Install the app on your repositories
  4. 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, never echo $SECRET
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

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.