Pull Request Builder for GitHub plugin

The Pull Request Builder for GitHub plugin let you configure Jenkins to verify pull requests on a GitHub project and check the proposed changes validates Continuous Integration criteria set on your Jenkins instance.

The feature was introduced in CloudBees Jenkins Enterprise 14.11.

Development teams using GitHub rely on pull request mechanism for code-review before some changes are adopted and merged into the mainstream development branch. This is a very convenient process as GitHub provides a nice UI to discuss changes and annotate modified lines in code. Manual code review anyway can’t catch all possible mistakes, and may be a waste of time when the proposed changes has some negative impact on project that the Jenkins continuous integration job can detect. The Pull Request Builder for GitHub plugin takes advantage of GitHub APIs to get notified when a pull request is created / updated, and can trigger a build to automatically check the proposed changes. The build status is then reported on pull request, and reviewer can just ignore an invalid pull request, as the requester can check the log and fix his changes.

Setting up Pull Request Builder for GitHub

The Pull Request Tester plugin is available within CloudBees Jenkins Enterprise update center. CloudBees Git Validated merge plugin is required, as Jenkins GitHub plugin.

For full setup automation, credentials have to be configured in Jenkins global settings. GitHub API authentication require to create an access token. We recommend you create a dedicated pseudo-user on GitHub to handle API interaction from Jenkins in GitHub, and have no interaction with actual developers profiles.

  • Go to your GitHub settings page.

  • In the left sidebar, click Personal Access Token.

  • Click Generate new token.

  • Give your token a descriptive name

  • Select the scopes to grant to this token. Pull request tester plugin require permission to administer repository hooks and access repositories: repo, public_repo, admin:repo_hook, repo:status.

  • Click Generate token.

  • Copy the token to your clipboard. For security reasons, after you navigate off this page, no one will be able to see the token again

Configure your access token in Jenkins and validate GitHub API access.

global config 201607
Figure 1. Global Configuration

You also can configure Jenkins so that it doesn’t manage the web hook for you, but then will have to ensure web hooks are well registered for all your repositories

Using Pull Request Builder for GitHub

plugin introduce a new trigger option to Jenkins jobs, "Build pull requests to the repository", which needs to be enabled. This option only makes sense if the job is building a project using a GitHub repository as SCM. Selecting this option will automatically register a web hook on GitHub so Jenkins get notified when pull requests are created/updated.

"Enable Git validated merge support" in the job configuration has to be enabled as well, even if you don’t use this feature by yourself, because Pull Request tester plugin relies on Git Validated Merge plugin.

As a pull request is opened on GitHub repository, Jenkins will trigger a build and report result in GitHub UI as "commit status" (a note associated to the latest commit of the pull request). Any update to the pull request (new commit pushed, or amendment to existing commits in pull request) will trigger another build and update the commit status.

Note: Merge process need to be done manually by a member with admin permissions in that repository.

commit status 201607
Figure 2. GitHub Commit Status (test failed in this case)