Child pages
  • GitHub pull request builder plugin

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Suggest replacement

You should probably migrate to GitHub Branch Source Plugin


This plugin builds pull requests in github and report results.

Wiki Markup




More up to date information is available on the:


When a new pull request is opened in the project and the author of the pull request isn't white-listed, builder will ask "Can one of the admins verify this patch?".


  • "retest this please" to start a new build


  • I recommend to create GitHub 'bot' user that will be used for communication with GitHub (however you can use your own account if you want).
  • The user needs to have push rights for your repository (must be collaborator (user repo) or must have Push & Pull rights (organization repo)).
  • If you want to use GitHub hooks have them set automatically the user needs to have administrator rights for your repository (must be owner (user repo) or must have Push, Pull & Administrative rights (organization repo))
  • Install the plugin.
  • Go to "Manage Jenkins" ``Manage Jenkins`` -> "Configure System" ``Configure System`` -> "Github ``GitHub pull requests builder" section.
  • If you are using Enterprise GitHub set the server api URL in "Github server api URL". Otherwise leave there "".
  • Set your 'bot' user's Access Token.
    • If you don't have generated your access token you can generate one in "Advanced...".
      • Set your 'bot' user's GitHub username and password.
      • Press the "Create Access Token" button
      • Copy the generated Access Token into the field "Access Token"
      • Clear the username and password fields
    • If you don't want to use Access Token leave the field empty and fill the username and password in "Advanced...".
  • builder`` section.
  • Add GitHub usernames of admins (these usernames will be used as defaults in new jobs).
  • Under Advanced, you can modify:
    • The phrase for adding users to the whitelist via comment. (Java regexp)
    • The phrase for accepting a pullrequest pull request for testing. (Java regexp)
    • The phrase for starting a new build. (Java regexp)
    • The crontab line. This specify default setting for new jobs.
    • The target branch whitelist.  This allows you to test only pull requests targeted for the branches in this list.
    • If you want to get comments posted to GitHub for each build, fill the "Published Jenkins URL", if you only want to use the GitHub status API, leave it empty.
  • Save to preserve your changes.
  • Allow raw HTML rendering. (See JENKINS-22028)
    • Manage Jenkins > Configure Global Security > Under "markup formatter", set to "raw HTML"
  • Under Application Setup
    • There are global and job default extensions that can be configured for things like:
      • Commit status updates
      • Build status messages
      • Adding lines from the build log to the build result message
      • etc.


  • If you are using Enterprise GitHub set the server api URL in ``GitHub server api URL``. Otherwise leave there ````.
  • A GitHub API token or username password can be used for access to the GitHub API
  • To setup credentials for a given GitHub Server API URL:
    • Click Add next to the ``Credentials`` drop down
      • For a token select ``Kind`` -> ``Secret text``
        • If you haven't generated an access token you can generate one in ``Test Credentials...``.
          • Set your 'bot' user's GitHub username and password.
          • Press the ``Create Access Token`` button
          • Jenkins will create a token credential, and give you the id of the newly created credentials. The default description is: ``serverAPIUrl + " GitHub auto generated token credentials"``.
      • For username/password us ``Kind`` -> ``Username with password``
        • The scope determines what has access to the credentials you are about to create
      • The first part of the description is used to show different credentials in the drop down, so use something semi-descriptive
      • Click ``Add``
    • Credentials will automatically be created in the domain given by the ``GitHub Server API URL`` field.
    • Select the credentials you just created in the drop down.
    • The first fifty characters in the Description are used to differentiate credentials per job, so again use something semi-descriptive
  • Add as many GitHub auth sections as you need, even duplicate server URLs
  • Save to preserve your changes.

Creating job:

  • Create a new job.
  • Add the project's GitHub URL to the "GitHub project" field (the one you can enter into browser. eg: "")
  • Select Git SCM.
  • Add your GitHub "Repository URL".
  • Under Advanced, set "refspec" to

    Code Block
  • In "Branch Specifier", enter


    Code Block

    or if you want to use the actual commit in the pull request, use

    Code Block
  • Under "Build Triggers", check "Github pull requests builder".
    • Add admins for this specific job.
    • If you want to use GitHub hooks for automatic testing, read the help for "Use github hooks for build triggering" in job configuration. Then you can check the checkbox.
    • In Advanced, you can modify:
      • The crontab line for this specific job. This schedules polling to GitHub for new changes in Pull Requests.
      • The whitelisted users for this specific job.
      • The organisation names whose members are considered whitelisted for this specific job.
  • Save to preserve your changes.
    Make sure you DON'T have "Prune remote branches before build" advanced option selected, since it will prune the branch created to test this build. As noted in issue #507 this may be achieved by unchecking 'Lightweight checkout'.

If you want to manually build the job, in the job setting check "This build is parameterized" and add string parameter named "sha1". When starting build give the "sha1" parameter commit id you want to build or refname (eg: "origin/pr/9/head").


  • ghprbActualCommit
  • ghprbActualCommitAuthor
  • ghprbActualCommitAuthorEmail
  • ghprbPullDescription
  • ghprbPullId
  • ghprbPullLink
  • ghprbPullTitle
  • ghprbSourceBranch
  • ghprbTargetBranch
  • ghprbCommentBody
  • sha1



Job DSL Support

The plugin contains an extension for the Job DSL plugin to add DSL syntax for configuring the build trigger and the pull request merger post-build action.

Here is an example showing all DSL syntax elements:

Code Block
job('example') {
    scm {
        git {
            remote {
    triggers {
        githubPullRequest {
            admins(['user_2', 'user_3'])
            userWhitelist(['', ''])
            orgWhitelist(['your_github_org', 'another_org'])
            cron('H/5 * * * *')
            triggerPhrase('OK to test')
            extensions {
                commitStatus {
                    context('deploy to staging site')
                    triggeredStatus('starting deployment to staging site...')
                    startedStatus('deploying to staging site...')
                    completedStatus('SUCCESS', 'All is well')
                    completedStatus('FAILURE', 'Something went wrong. Investigate!')
                    completedStatus('PENDING', 'still in progress...')
                    completedStatus('ERROR', 'Something went really wrong. Investigate!')

See the README on GitHub for the latest information.


>= 1.25

Changelog for 1.25 and upward is maintained on the plugins github page


Use signature checking for webhooks if desired.
Add custom messages to status updates and a custom url field.


Use credentials plugin for username/password combinations and tokens.
Support multiple GitHub endpoints.


Fix issue where if a project was disabled the Jenkins Trigger process would crash
Fix commit status context
Add one line test results for downstream builds
Miscellaneous bug fixes


Move commit status over to extension form. It is now configurable, satisfying #81, #73, and #19 at least.


Move all commenting logic out into extensions.


Null Pointer fix for trigger.
Added clarity to error message when access is forbidden.


PullRequestMerger now notifies the taskListener of failures.
AutoCloseFailedPullRequest has been extracted from the published URL check.


More work for disabled builds.
Unified tabs to spaces.
Updates to the tests, and added some tests.


Add support for folder projects.
Correcting issue with default credentials.
Correcting issue with ghRepository being null when it shouldn't be.
Ignoring case when matching repo to url.
Changing the wording for pull requests that are mergeable.
Change requestForTesting phrase to a textArea.
Check if project is disabled, if it is then don't do anything.



A comment file can be created during the build and added to any comment made to the pull request. podarok#33
Added a


[skip ci


] setting, that can be changed. Adding the skip statement to the pull request body will cause the job not to run. sathiya-mit#29
Escaping single quotes in log statements tIGO#38
Fixed owner name deduction from url on github hook handling nikicat#40
Removed unused Test field from the config



Replacing deprecated Github.connect method. tIGO#39
Added a merge plugin for post build. If the build is successful, the job can specify conditions under which the pull request "button" will be pressed.


Fixes issue with checking rate limits for GitHub Enterprise
Internal refactorings
Fixes checking of TriggerTimer (JENKINS-22550)


Major reduction in the number of requests made to GitHub to avoid rate limit issues
Fixed changelog for a build so it reports differences between Pull Request build
Fixes bug on getting author email address from GitHub APIs
Updates warning message is URL isn't set on the GitHub project plugin
Adds some additional parameters to the build, such as the source branch, pull request link, etc.
Success/failure message now put into the comment on Pull Requests

1.10 - 1.11.1

Not publicly released.