Using a jenkins pipeline to build github pull requests

Question

This seems to be one of the more important, but less understood and documented features of GH and Jenkins, which seems to defeat the purpose of CI entirely ...

I'm trying to setup a simple, "kick off a build when a pull request is opened" Job in Jenkins. I've scanned though dozens of posts, some several years old, but have yet to find a solution that actually works, start-to-finish. I'm using GH 2.15.4 and Jenkins 2.89.3 with the GH Pull Request Builder plug-in. I've tried setting up a pipeline job, and a freestyle project, following various "how to" posts and docs. Nothing works as expected. Not even close. I've managed to get some functionality working, but not without a lot of trial-and-error experimenting, which doesn't leave me with a warm-fuzzy in using it. Webhooks are equally worthless in accomplishing what is needed, as nothing seems to fire off a job in Jenkins, regardless of how it is configured.

For starters, are there any references or docs that explain what the following status checks are that are automatically created by Jenkins:

continuous-integration/jenkins/branch

continuous-integration/jenkins/pr-head

continuous-integration/jenkins/pr-merge

Apparently there is no way to delete or edit these ... they just "appear" courtesy of Jenkins. I've seen some discussions, but some explanations contradict one another, so they may just be outdated, inaccurate, etc. I want to know "what does what" so I know which should be 'required' as part of the PR status check.

Any pointers would be appreciated!

Answer 1

I agree, this problem is tricky because Jenkins and its plugins have changed so much throughout the years. Let me tell you how I accomplished what you're asking for. I will post all of my version numbers (mostly up to date).

Jenkins Version: 2.176.1 (java -jar /usr/share/jenkins/jenkins.war --version)

Plugins

• github 1.29.4
• github-api 1.9
• github-branch-source 2.5.3
• github-pullrequest 0.2.5
• pipeline-github-lib 1.0

Also, I use the Blue Ocean interface, which might affect things (who knows)

• blueocean 1.17.0
• blueocean-git-pipeline 1.17.0
• blueocean-github-pipeline 1.17.0

Github Webhooks

First off, set up webhooks for your system. This is a good guide for Github Webhooks Go to your Github repository and click on the Settings tab. Then select 'Webhooks' in the left menu:

The URL of my Jenkins setup is https://jenkinsci.dorian.com. So, in the 'Payload URL' box, I put https://jenkinsci.dorian.com/github-webhook/

I left the settings as "application/json" and "send me everything" and "active"

The Webhooks area has a handy 'Recent Deliveries' section which can show you if your webhooks are making it to Jenkins. At first, I had the wrong URL so mine has red Xs next to them. Now, they're all green checkmarks.

Github Access Token

Many guides suggest that you provide Jenkins with a personal access token to communicate with your repo. To do that, go to your account avatar in the top right and select Settings -> Developer Settings -> Personal access tokens->Generate Token

Put whatever you want for the description. Under 'select scopes', if you just want it to work, select every checkbox in the list.

I selected:

• repo:status
• write:repo_hook
• read:repo_hook
• admin:org_hook

Click save and you'll be shown your secret key. Copy this somewhere safe (we'll use it soon).

Configuring Jenkins

Now for the hard part. Try and install all of the plugins I've listed above.

Go to Jenkins-Manage Jenkins->Configure System

Locate the Github section and click Add Github Server

• Name: Github
• Api URL: https://api.github.com
• Manage Hooks: true

Under credentials, click "Add." You'll be brought to a menu. Select "Secret Text"

• Scope: Global
• Secret: paste your access token from earlier
• ID: (I left this blank)
• Description: DorianGithubCreds

Hit save. Then, select DorianGithubCreds from the credentials list.

To test, hit "Test Connection." Mine returns 'Credentials verified for user dnrahamim', rate limit: 4998

Now go down to Github Pull Request Builder

• GitHub Server API URL: https://api.github.com
• Jenkins URL override: (blank)
• Shared Secret: (blank)
• Credentials: DorianGithubCreds
• Auto-manage webhooks: true
• Everything else is blank

Configure Job

Go to the job that should be building your repo Select 'Configure' in the left menu

Under Projects->Github Organization

• Credentials: DorianGithubCreds
• Owner: Dorian
• Behaviors:
  • Discover branches
    • Strategy: Exclude branches that are also filed as PRs
  • Discover pull requests from origin
    • Strategy: Merging the pull request with the current target branch revision
  • Discover pull requests from forks
    • Strategy: Merging the pull request with the current target branch revision
    • Trust: From users with Admin or Write permission
• Project Recognizers
  • Pipeline Jenkinsfile
    • Path: Jenkinsfile (my Jenkinsfile is in the project root)
• Build Strategies: (intentionally blank)

Notifications

Now, when I do a pull request, or whenever I post a change to a pull request, Jenkins run a fresh build for that branch.

The Pull Request itself in Github also lists its "Status Checks" at the bottom. When the build is pending, the status check is yellow. If it succeeds it gets a green checkmark. If it fails, it gets a red X.

I initially had a problem because I had an old Jenkins box which was also configured to manage Github webhooks and build pull requests. Its builds were failing so its notifications were the ones getting through to my pull request. I fixed that problem by preventing that old Jenkins box from building my newest branches. Once the old Jenkins box stopped building, the notifications from the new Jenkins box made it through to Github.

Wrapping up

That's it! That's everything I intentionally configured. Please try out my configuration and see if it works for you. Let me know if I left anything out.

The hard part with configuring Jenkins with Github is that, although there are many guides, the suggestions often conflict with each other and very many are out of date (sometimes even official documentation is out of date).

Nonetheless, here are some Resources:

1. This is a good guide for Github Webhooks
2. Github's Whitepaper on CI with Jenkins (It doesn't explain much in detail but it gives a good overview)
3. Github pull request builder plugin
4. Semi-official SO post for showing build status on Github repo