CloudBees Pull Request Builder for GitHub plugin

3 minute read
CloudBees removed this plugin from the CloudBees Assurance Program (CAP) in January 2023. Please contact CloudBees Support if you have any concerns or questions.

The CloudBees Pull Request Builder for GitHub plugin lets 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 the Update Center. The 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 does not manage the web hook for you, but then you will have to ensure that the web hooks are well registered for all of your repositories.

Using

The CloudBees Pull Request Builder for GitHub plugin plugin includes 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 CloudBees 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)
In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.