Connect GitHub, Webhooks and Multibranch Pipelines

Anil Jalela · Published Aug 12, 2026 · 5 min read

A useful Jenkins and GitHub integration discovers branches and pull requests, validates the repository's Jenkinsfile, reports status, and keeps untrusted changes away from protected credentials. This guide configures the connection with a GitHub App, a webhook and a Multibranch Pipeline.

Choose the integration model

Use a GitHub App for managed organization integration. Grant only the repository metadata, contents, pull-request, checks and webhook permissions actually required. Install it only on selected repositories during rollout.

Prepare Jenkins and its public endpoint

1. Install and review the GitHub Branch Source, Pipeline and Credentials plugins.
2. Publish Jenkins behind HTTPS through an approved reverse proxy. Set the Jenkins URL to the same external origin.
3. Permit GitHub webhook traffic to the webhook endpoint without exposing the administration interface.
4. Keep anonymous administrative and job-configuration access disabled.

The commonly used webhook endpoint is:

https://jenkins.example.com/github-webhook/

Create and store the GitHub App credential

1. In GitHub organization settings, create a GitHub App with a clear owner and callback/webhook URLs for this Jenkins service.
2. Generate its private key and record the App ID. Store the downloaded key temporarily in a protected administrator location.
3. Install the App on the selected organization and repositories.
4. In Jenkins, add a GitHub App credential at folder scope. Supply the App ID and private key, then test the API connection.
5. Delete the temporary key copy after the managed credential and recovery copy are confirmed.

Do not print the private key, installation token or webhook secret. Credentials masking reduces accidental disclosure but cannot make an untrusted shell step safe.

Create a Multibranch Pipeline

1. Select New Item > Multibranch Pipeline.
2. Add a GitHub branch source, choose the GitHub App credential, and select the repository.
3. Configure branch and pull-request discovery for your review policy. Do not expose protected credentials to code from untrusted forks.
4. Set the script path to Jenkinsfile unless the repository intentionally uses another reviewed path.
5. Save and run Scan Multibranch Pipeline Now. Jenkins creates jobs for discovered branches containing a Jenkinsfile.

pipeline {
  agent { label 'linux' }
  options { skipDefaultCheckout(true) }
  stages {
    stage('Checkout') {
      steps { checkout scm }
    }
    stage('Verify revision') {
      steps {
        sh 'set -eu; git rev-parse HEAD; git status --porcelain'
      }
    }
    stage('Test') {
      steps { sh 'set -eu; ./ci/test.sh' }
    }
  }
  post { always { junit testResults: 'reports/*.xml', allowEmptyResults: true } }
}

Configure and test the webhook

Add or confirm the webhook created for the App. Use JSON, HTTPS and a secret. Send a test delivery, inspect its HTTP response, then push a test branch. A successful webhook should cause indexing or a build without giving the sender permission to change job configuration.

# Reverse-proxy examples: locate webhook requests and status codes.
sudo journalctl -u jenkins --since '-15 minutes' --no-pager
sudo tail -n 100 /var/log/nginx/access.log
sudo tail -n 100 /var/log/nginx/error.log

Protect pull-request builds

• Build untrusted pull requests on isolated agents without deployment, signing or production credentials.
• Require repository review and protected-branch checks before merge.
• Use separate jobs or explicit trusted-branch conditions for artifact publication and deployment.
• Remember that a pull request can modify the Jenkinsfile and any script it calls.

stage('Publish') {
  when {
    allOf {
      branch 'main'
      not { changeRequest() }
    }
  }
  steps { sh 'set -eu; ./ci/publish.sh' }
}

Troubleshooting map

Unsafe patterns

Unsafe: embedding a token in a repository URL leaks it through configuration, logs and process inspection:

https://USERNAME:[email protected]/OWNER/REPOSITORY.git

Store a scoped credential in Jenkins and select it by credential ID. Unsafe: running fork pull requests with production credentials allows changed repository code to exfiltrate them. Separate validation from trusted publication and deployment.

# Verify repository state inside the Multibranch run
git remote -v
git rev-parse HEAD
git show --no-patch --format='%H %P %cI %s' HEAD
# GitHub webhook endpoint
https://jenkins.example.test/github-webhook/
# Jenkins branch indexing log must show the same repository and head revision

Official references

• Branches and pull requests
• GitHub Branch Source plugin
• Credentials guidance