Child pages
  • GitHub pull request builder plugin

Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

You should probably migrate to GitHub Branch Source Plugin

This plugin builds pull requests in github and report results.

Plugin Information

View GitHub Pull Request Builder on the plugin site for more information.

The current version of this plugin may not be safe to use. Please review the following warnings before use:

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

This plugin is up for adoption. Want to help improve this plugin? Click here to learn more!

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?".

  • "ok to test" to accept this pull request for testing
  • "test this please" for a one time test run
  • "add to whitelist" to add the author to the whitelist

If the build fails for other various reasons you can rebuild.

  • "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`` -> ``Configure System`` -> ``GitHub pull requests 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 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.
  • 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

  • In "Branch Specifier", enter


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

  • 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").

Environment Variables

The plugin makes some very useful environment variables available.

  • 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:

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.


Added job specific triggers.
Added more informations as job parameters.
Fix support for gh-ent token generation. JENKINS-17334
Lookup PR detailed information for each PR. JENKINS-17852
Fix closing PR.
various bugfixes


Support auto-close at build level
add pull id and target branch to environment variables
fix GitHub Hooks when authentication is required on Jenkins
various bug fixes and improvements


implemented support for GitHub hooks
added button for generating API token


option for specifying how to mark unstable builds in GitHub
Close failed pull requests automatically if plugin admin configured it
customizeable pass/fail comments
Refactoring of code
help description in Jenkins configuration


checkbox enabling sending comments when update of comment status fails
option to enter organisations which members are whitelisted
support for Enterprise GitHub
link to pull request into build description


Changed comment commands - phrases for testing once, pull request or add user to whitelist
"test this please" starts new build
"ok to test" allow pull request for building
"add to whitelist" add user to whitelist


Add published URL feature.
Enable connection to GitHub Enterprise instances.
Enable authentication via a token.
When automatic merge is possible, build the merge.


Use commit status API instead of comments for reporting results.


  1. Unknown User (marco_dejong)

    Hi there,
    I don't know if I should report this as actual bug, but as soon as I try to configure the job as described as above,
    I get a "Exception: java.lang.NullPointerException". After this the job will never actually try and fetch data as configured in crontab.
    Posting some ugly data after this...
    Status Code: 500
    Exception: java.lang.NullPointerException
    javax.servlet.ServletException: java.lang.NullPointerException
    	at org.kohsuke.stapler.Stapler.tryInvoke(
    	at org.kohsuke.stapler.Stapler.invoke(
    	at org.kohsuke.stapler.MetaClass$6.doDispatch(
    	at org.kohsuke.stapler.NameBasedDispatcher.dispatch(
    	at org.kohsuke.stapler.Stapler.tryInvoke(
    	at org.kohsuke.stapler.Stapler.invoke(
    	at org.kohsuke.stapler.Stapler.invoke(
    	at org.kohsuke.stapler.Stapler.service(
    	at javax.servlet.http.HttpServlet.service(
    	at winstone.ServletConfiguration.execute(
    	at winstone.RequestDispatcher.forward(
    	at winstone.RequestDispatcher.doFilter(
    	at hudson.util.PluginServletFilter$1.doFilter(
    	at hudson.plugins.greenballs.GreenBallFilter.doFilter(
    	at hudson.util.PluginServletFilter$1.doFilter(
    	at hudson.util.PluginServletFilter.doFilter(
    	at winstone.FilterConfiguration.execute(
    	at winstone.RequestDispatcher.doFilter(
    	at winstone.FilterConfiguration.execute(
    	at winstone.RequestDispatcher.doFilter(
    	at org.acegisecurity.ui.ExceptionTranslationFilter.doFilter(
    	at org.acegisecurity.providers.anonymous.AnonymousProcessingFilter.doFilter(
    	at org.acegisecurity.ui.rememberme.RememberMeProcessingFilter.doFilter(
    	at org.acegisecurity.ui.AbstractProcessingFilter.doFilter(
    	at org.acegisecurity.ui.basicauth.BasicProcessingFilter.doFilter(
    	at org.acegisecurity.context.HttpSessionContextIntegrationFilter.doFilter(
    	at winstone.FilterConfiguration.execute(
    	at winstone.RequestDispatcher.doFilter(
    	at org.kohsuke.stapler.compression.CompressionFilter.doFilter(
    	at winstone.FilterConfiguration.execute(
    	at winstone.RequestDispatcher.doFilter(
    	at hudson.util.CharacterEncodingFilter.doFilter(
    	at winstone.FilterConfiguration.execute(
    	at winstone.RequestDispatcher.doFilter(
    	at winstone.RequestDispatcher.forward(
    	at winstone.RequestHandlerThread.processRequest(
    	at java.util.concurrent.Executors$
    	at java.util.concurrent.FutureTask$Sync.innerRun(
    	at winstone.BoundedExecutorService$
    	at java.util.concurrent.ThreadPoolExecutor.runWorker(
    	at java.util.concurrent.ThreadPoolExecutor$
    Caused by: java.lang.NullPointerException
    	at org.jenkinsci.plugins.ghprb.GhprbTrigger.start(
    	at org.jenkinsci.plugins.ghprb.GhprbTrigger.start(
    	at hudson.model.AbstractProject.submit(
    	at hudson.model.Project.submit(
    	at hudson.model.Job.doConfigSubmit(
    	at hudson.model.AbstractProject.doConfigSubmit(
    	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    	at sun.reflect.NativeMethodAccessorImpl.invoke(
    	at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    	at java.lang.reflect.Method.invoke(
    	at org.kohsuke.stapler.Function$InstanceFunction.invoke(
    	at org.kohsuke.stapler.Function.bindAndInvoke(
    	at org.kohsuke.stapler.Function.bindAndInvokeAndServeResponse(
    	at org.kohsuke.stapler.MetaClass$1.doDispatch(
    	at org.kohsuke.stapler.NameBasedDispatcher.dispatch(
    	at org.kohsuke.stapler.Stapler.tryInvoke(
    	... 58 more
  2. Unknown User (recampbell)

    That's the most obscure plugin name I've ever seen. Can you rename it to github-pull-request-builder ?

  3. Unknown User (mikedougherty)

    This should use a github API token instead of username and password, and it should also use the API made explicitly for this feature.

    1. Unknown User (celeduc)

      Agreed 100%. The password in clear is particularly frightening.

  4. Unknown User (mdelapenya)

    Hi all!

    Could you explain how pull request status is changed in Github? And which configuration of this plugin (related to users: repos' admin, whitelisted, etc) is necessary to mark that status in every Jenkins build?


  5. Unknown User (mdelapenya)

    It also would be nice to configure the message automatically written in the pull request: "Can one of the admins verify this patch?"


  6. Unknown User (msabramo)

    I just upgraded from 1.9 to 1.11.2 and our pull requests stopped building. Downgraded and they work again.

    If you email me, I can try to get you more info to debug the issue. Could even hope on IM or IRC if you want.

    1. Unknown User (msabramo)

      OK, I did a little more digging and eventually discovered that 1.11.2 has a known issue with the rate limit API of GitHub Enterprise installations. It is fixed in the following pull request, which has been merged:

      but there is not yet an official release of the plugin with this change.

      Can we get a new release please?

  7. Unknown User (jbrejner)

    It seems I have difficulties making this plugin work with multiple repositories ? I want this plugin to look for PR's on a private repository on github, and that works nice - but for testing the contents of the github repo, I need the contents of another repository (locally hosted on our inside). So I use the "Mulitple SCM's" plugin, to clone both repositories, and it appears that this plugin attempts to find the PR SHA in both repositories - which naturally fails.

    Am I correct in assuming that multiple repositories is not supported by the plugin ?

    Can you suggest a way to achieve my goal in some way ?

    1. Unknown User (tomoe)

      I think I'm getting the same. I get the following error on the 2nd github project, which is not related to the one that pull request builder is listening on.  

      using .gitcredentials to set credentials
       > git config --local credential.helper store --file=/tmp/git4437896140776317333.credentials
       > git fetch --tags --progress +refs/heads/*:refs/remotes/origin/*
       > git config --local --remove-section credential
       > git rev-parse origin/pr/220/merge^{commit}
      FATAL: Command "git rev-parse origin/pr/220/merge^{commit}" returned status code 128:
      stdout: origin/pr/220/merge^{commit}
      stderr: fatal: ambiguous argument 'origin/pr/220/merge^{commit}': unknown revision or path not in the working tree.
      Use '--' to separate paths from revisions
      hudson.plugins.git.GitException: Command "git rev-parse origin/pr/220/merge^{commit}" returned status code 128:
      stdout: origin/pr/220/merge^{commit}
      stderr: fatal: ambiguous argument 'origin/pr/220/merge^{commit}': unknown revision or path not in the working tree.
      Use '--' to separate paths from revisions
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommand(
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommand(
      	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.revParse(
      	at hudson.plugins.git.GitAPI.revParse(
      	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
      	at sun.reflect.NativeMethodAccessorImpl.invoke(
      	at sun.reflect.DelegatingMethodAccessorImpl.invoke(
      	at java.lang.reflect.Method.invoke(
      	at hudson.remoting.RemoteInvocationHandler$RPCRequest.perform(
      	at hudson.remoting.RemoteInvocationHandler$
      	at hudson.remoting.RemoteInvocationHandler$
      	at hudson.remoting.UserRequest.perform(
      	at hudson.remoting.UserRequest.perform(
      	at hudson.remoting.Request$
      	at hudson.remoting.InterceptingExecutorService$
      	at java.util.concurrent.ThreadPoolExecutor.runWorker(
      	at java.util.concurrent.ThreadPoolExecutor$

      I'm now trying to workaround by checking out repos manually by shell executor at the beginning of the job. But it'd be great if this use case is supported.

  8. Unknown User (elordahl)

    Can you guys update the ChangeLog?

  9. Unknown User (elordahl)

    Can you guys update the ChangeLog?

  10. Unknown User (gruberro)

    Hi guys,

    I've ran several times into the problem that double quotes or an apostrophe in a commit (e.g. for a revert commit) breaks the build pipeline. The build itself is done with Ant and the non-escaped auto-attached ghprb-params are breaking.

    [build] $ ant -file build.xml -DghprbTriggerAuthorEmail= -DghprbTargetBranch=master -DghprbSourceBranch=fix-wsod "-DghprbActualCommitAuthor=Foo Bar" -Dsha1=origin/pr/1337/merge -DghprbPullLink= -DghprbActualCommit=d4668b1798373a99e0f845bbbc3e9f01337dfda7 -DGIT_BRANCH=fix-wsod -DghprbPullAuthorEmail= -DghprbTriggerAuthor= -DghprbPullId=1337 "-DghprbPullTitle=Reverts "Bad commit"" "-DghprbPullDescription=GitHub pull request #1337 of commit d4668b1798373a99e0f845bbbc3e9f01337dfda7 automatically merged."
    /usr/bin/ant: 1: eval: Syntax error: end of file unexpected

    Any suggestion of how to work around or where to write a feature request (gpprb vs. Ant-builder)?

  11. Unknown User (meteorping)

    Hello, all

    I am using the latest one, but in configuration page I cannot find a place to use existed git access token.

    What should I do if I want to use an existed access token.

    1. Unknown User (davidtanner)

      Use the Add button to add a set of credentials.  Use Secret Text to add the token, and Username Password for user setup.

      1. Unknown User (meteorping)

        yes, I tried that way, but it always failed for the message like attached.

        Finally I turn to 1.22.4 version, and it works for me then.

  12. Unknown User (gargmohit3890)

    Hi All,

    I am using this plugin with latest version. I am configuring a job using this plugin and finding some unexpected behaviour as listed below:

    1. In admin list option, I providing an username who is not a admin and I am not getting an error msg.

    2. In white-list option, I am providing single username(So the job will be triggered only for this user), but job is triggered for any user.

    The above two points are my understanding. Am I understanding correctly.

    If any one knows the about admin-list and white-list, please revert.


    Mohit Garg

  13. Unknown User (efmoyano)

    Is there any way to get this plugin working with the pipeline feature? I tried to implement it in the JenkinsFile but i wasn't able to call the plugin, i will appreciate any help.



  14. Unknown User (brianjmurrell)

    Is there any way to make this plugin work with matrix/multi-configuration jobs so that each child of the matrix updates it's own GH context?

    As it is now, each child just overwrites the same context so last child wins.

  15. Unknown User (alec_m)

    Does this plugin have the capability to detect out-of-date Pull Requests and then merge new changes into those pull requests and trigger Jenkins jobs to run against them automatically?

    I have 2 Pull Requests (PR1, PR2) opened against the same master branch.  Both of them were opened in parallel, and this plugin behaves as normal, triggering builds against each of these.  Say that PR2 succeeds and is merged into master, and PR1 lags behind waiting for a review or something.  Does this plugin have the capability to automatically detect this merge was completed, then update PR1 with the new changes to master, and then trigger a build to test the original PR1 commits with the new changes from PR2's merge?

    I'm aware of which will update a pull request in Github to let the user know that particular pull request is out of date and needs to be updated before it can be merged.  The use could then click on 'Update Branch' and then Github would make a new commit with those changes in it.  I'm just wondering if there is a way to automate this whole process via Jenkins.  Would this be the plugin for that job, is there another one that will do it, or would it just be best to come up with a script on my own that does this?

  16. Unknown User (yauhen_mihura)

    Hello,   Could you please add to plugin events pull_request_review? I would like to trigger job after approving pull request review.