Child pages
  • Stash PullRequest 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

Plugin Information

View Stash Pullrequest Builder on the plugin site for more information.

This Jenkins plugin builds pull requests from an Atlassian Bitbucket Server (formerly known as Stash) and reports the build result as a comment on the pull request page. Builds are normally triggered by creating or updating to the pull request, but it's also possible to trigger a build with a comment.

Prerequisites

Configuration

Please see the README.md file

If you have any questions, please ask them on Gitter: https://gitter.im/jenkinsci/stash-pullrequest-builder-plugin

Versions

See CHANGELOG on Github

19 Comments

  1. Unknown User (lechlitnerd)

    At the moment, each time a new comment is added to the Stash Pull Request, Jenkins is picking it up as a change and re-running the tests.  Is there a configuration that can be updated or set to avoid this?  We only want to re-run the tests if the commit changes.

  2. Unknown User (lam2558)

    Is there a way to exclude specific branches by name?

  3. Unknown User (jimklimov)

    Thanks for the plugin. Just gave it a spin, using it as a trigger to launch another job, which has some complicated default/changeable build params for developers, so it was easier to call it than hack into it.

    A few tricks to note are:

    • I added to that called job's build params a CI_FORK_REPO, CI_FORK_BRANCH and CI_FORK_REFSPEC build param, and referenced them as the git repo, branch and refspec to check out. We actually had the former two in place all over our jobs, inherited when one calls another (mostly we use multiphase in this setup), so developers could run their version of code against "standard conditions" on independent platform (not their workstation) before posting a pull request. The default Repo is one from a selectable list (Extensible list or a Global variable, depending on a job), the branch is a String (defaults to `*master`) and now the refspec is also a string, defaults to empty unless set by this plugin calling that job.
    • I defined a job that does not check out anything by itself, just has the Stash pullrequest builder ticked and fields filled out per article above. As its activity it "Triggers/calls builds on another job" and calls the specified job (and waits for it to finish). Our typical setup adds Build on same node, use same Build parameters (though there are none, at least explicitly, in this stash-poller job), and defines a few parameters for the called job:

      CI_REPO_FORK=ssh://git@stash.hostname.com:7999/${destinationRepositoryOwner}/${destinationRepositoryName}.git
      CI_REPO_REFSPEC=+refs/pull-requests/*:refs/remotes/origin/pr/*
      CI_REPO_BRANCH=origin/pr/${pullRequestId}/from

      Note to NOT use quoting in these definition of values - those quotes propagate to Git client and upset it (wink) Don't forget the "ssh://" schema part, either.

    • The Stash Host is a base URL, not bare hostname, so don't forget to type in the schema ("http://")
    • The credentials for polling Stash REST API are an account and password (for web-interface); credentials for Git over SSH are a ssh-key added to the profile of that same account on Stash. That account is added to the organizations and developers' repos with a right to read. Note that the SSH key added to a profile can not be explicitly added to a project and vice-versa. If you want to access some projects by a dedicated key - it must be a separate key in SSH and credential in Jenkins.
      • Thinking of it, we might use http:// for repo access too... at least to read them. For some reason we do not. 
        UPDATE: tested that we can, and see also the nits below. The corresponding format would be:

        CI_REPO_FORK=http://stash.hostname.com/scm/${destinationRepositoryOwner}/${destinationRepositoryName}.git

        Note that the project names are "as is" (lowercased), and user names are prefixed with a tilde character. Also note that your stack of called jobs would then have to use the HTTP (not ssh-key) credentials to access the repo over this transport, at least if the repo is not marked as publically accessible (otherwise, it can allow anonymous HTTP cloning). If your Stash admins did not block HTTP cloning (which is possible and some recommend), you can enjoy faster checkouts over HTTP, or so they say - in my few tests it was indeed marginally faster, but not enough to be a game-changer by itself.

    • The Jenkins-cron granularity for 1 minute should be specified as an asterisk; the soft-scheduler syntax with `H/1` is not 1 minute but 1 hour, or documented so per long-standing bug (https://issues.jenkins-ci.org/browse/JENKINS-22129 and other posts). The `H/2` is indeed around once every two minutes.
    • "test this please" in comments to the PR is indispensable while tinkering with the recipe on Jenkins side, and unchanged code in Git (wink)
    • I also added a Stash notification plugin as a post-job task, so the Stash PR interface has an icon to report the statistics of PR builds happening and passing or not. Ultimately it can be among automated criteria that the PR can be merged.

    • Per JENKINS-35219 - Getting issue details... STATUS  note to mark Build if PR is mergeable in the polling job config. UPDATE: See the post below for alternative solution, if requiring mergeability is too harsh for your practical use-case.

    One thing slightly missing for ease of integration is a prepopulated variable with the hostname (or URL) that should be passed to Git client - having to type in "ssh://git@example.com", and retype when making jobs for different stashes, is annoying (wink) I posted a bug on this: JENKINS-46605 - Getting issue details... STATUS  (including details of URLs reported back by Stash REST API).

    Another, maybe related to recent security revisions in Jenkins core, is that the job description provided by the plugin (I guess) is posted as verbatim HTML markup of the a-href tag with URL to PR web-interface enclosing the title of the PR. This HTML markup ends up seen in both the Jenkins interface (list of built jobs on the left) and in the notifications posted back to Stash (not the PR comments, but the "X builds failed" summary and the popup that details it).

    • UPDATE: JENKINS-22028 - Getting issue details... STATUS   details about enabling HTML markup in Jenkins Web-GUI, and it works for the job list. The notifications posted back to Stash (not comments) still have the verbatim markup, but that's probably the other plugin's problem.
    1. Unknown User (jimklimov)

      UPDATE: As an alternative to requiring "Build if PR is mergeable" above (this checkbox indeed avoided testing PRs that were deemed not readily mergeable), or similarly requiring "Build only if Stash reports no conflicts", the issue behind JENKINS-35219 can be worked around by crafting the request ourselves. For this I defined an additional "Execute Shell" step in the PR polling job described above, to be executed before triggering/calling the build on actual job which is the implementation of our test. This new step calls the Stash REST API with the curl (command-line HTTP client; on platforms that do not have it you might use wget as well, or many other equivalent methods to GET an HTTP request) to trigger the lazy-merge attempt (or fail one, does not matter here) so the git refspecs are re-calculated.

      This workaround as described only applies if you have PR poller and actual builder in separate jobs. Otherwise, CI is checked out (with wrong refspec) before the build steps run. An alternative solution is to post the script provided below into "" category, but then you'd have to hardcode the username and password for Stash REST API access, it seems.

      #
      # Workaround for broken git references that appear due to PRs,
      # popping up in other jobs trying to use just the master branch.
      #
      # See https://issues.jenkins-ci.org/browse/JENKINS-35219 and
      # https://community.atlassian.com/t5/Bitbucket-questions/Change-pull-request-refs-after-Commit-instead-of-after-Approval/qaq-p/194702
      
      set +x
      
      echo "Triggering lazy-merge of the PR on stash, by inspecting the special URL..."
      curl -k http://${STASH_USERNAME}:${STASH_PASSWORD}@stash.hostname.com/rest/api/latest/projects/${destinationRepositoryOwner}/repos/${destinationRepositoryName}/pull-requests/${pullRequestId}/merge

      Response from the command should be a meaningful JSON not with an authentication error (smile) In my case it was: 

      {"canMerge":false,"conflicted":false,
       "vetoes":[{"summaryMessage":"Requires approvers","detailedMessage":"You need 1 more approval before this pull request can be merged."}]}

      The login values for curl come from Jenkins credential storage, courtesy of the Credentials Binding Plugin and https://support.cloudbees.com/hc/en-us/articles/203802500-Injecting-Secrets-into-Jenkins-Build-Jobs how-to. In my simpler case, the credential was already stored and used for other REST API calls, and I only had to click Build Environment / Use secret text(s) or file(s), and selected a "Username and password (separated)" which I named STASH_USERNAME and STASH_PASSWORD, and picked the same credential used for the Stash-Jenkins PR integration. Note that if you don't use set +x, Jenkins should replace the credentials by asterisks in the log; but better safe than sorry (wink)

      Note that in our case the credentials are chosen to not upset the URL parser (no special characters that are part of URL markup and must be percent-encoded); you may have to add the encoder into the script above if your passwords use the @:/ and similarly important characters.

  4. Unknown User (dokaspar)

    What is the difference of this plugin to the bitbucket-pullrequest-builder-plugin?

    Are they solving different problems, is one of them deprecated, or are they just two alternatives created by different authors?

    1. Unknown User (jimklimov)

      I'd say the primary one is on the tin, per their READMEs, one is for Bitbucket.org (the cloud service), the other is for on-premise Stash instances (later rebranded to Bitbucket name as well). "This plugin was inspired by the GitHub & BitBucket pull request builder plugins." - this likely explains why many configuration variables are named the same.

      There may be functional differences as well (e.g. with Stash PR builder, we can set up the URL to the instance as a global Jenkins config value, and individual PR jobs just use that), not sure if there's something else. Not even sure which one end up in our case to query and build the on-premise Stash we track as an Organization Folder with the Pipeline support - likely that other one. In the end we've kept both older dedicated PR jobs and the new pipeline support active, because Stash PR builder can query the magic Stash REST API to recalculate ephemeral PR branches before build, so they can be resolved as the target (e.g. upstream/master) branch state changes; had some issues without that feature active.

  5. Unknown User (dokaspar)

    Thanks for the previous answers. I now managed to set up a working Jenkins job that correctly triggers on pull requests.

    However, manually triggering of my job causes a build failure, because the variables ${destinationRepositoryOwner} and ${destinationRepositoryName} are unknown in that case. For example:

    1. build the master branch when triggered manually?
    2. disable manual triggers?
    1. Unknown User (jimklimov)

      Indeed, same for us. Just don't do it (smile)

      To rebuild a PR (e.g. after sporadic failure in code like race conditions, fixed issue on test-farm's side, updated scripts and other stuff outside the tested branch that can influence the results), go to the open pull request in Stash web-gui and add a comment that includes "test this please" (see above for syntax and additional setup like build arg passing).

  6. Unknown User (a_johri)

    Where can I find the jobdsl syntax for this plugin?

  7. Unknown User (emangual)

    Is the use of wildcard supported under "Build PR targetting only these branches"? I could not get this to work.

  8. Unknown User (dzmitryh)

    Guys thanks for the great plugin! Quick question. Is there any way to attach code coverage information as part of this build status comment ? Has anyone done it ?

  9. Unknown User (proski)

    Please fix getting the Jenkins root URL with the new Jenkins versions. Without the fix, the Stash posts have an error message instead of a link to Jenkins. The pull request is on GitHub: https://github.com/jenkinsci/stash-pullrequest-builder-plugin/pull/27

    1. Unknown User (jimklimov)

      Note that you can build your own with `mvn package`.

      The HPI I use at work includes I think all or most of the PRs against the jenkins fork and nemccarthy's origin, which is easily done at home with a `git merge` while waiting for upstream to wake up.

      Hope this helps, Jim

  10. Unknown User (yjagdale)

    Hello Team,


    I am using    V#1.7.0  - I am facing issue with build trigger for type project.  Exactly same config is running for free-style or maven project but not for Pipeline project.

    Does anyone tried this? If working let me know the steps:- 


    Build Trigger config


    Jenkins SCM config

  11. Unknown User (eyalg1972)

    Hi,


    I am trying to use the plugin (version 1.7.0), I receive the error-


    WARNING: stashpullrequestbuilder.stashpullrequestbuilder.StashBuildTrigger.run() failed for org.jenkinsci.plugins.workflow.job.WorkflowJob

    Java.lang.NullPointerException

    at stashpullrequestbuilder.stashpullrequestbuilder.StashBuildTrigger.run(StashBuildTrgger.java:295)


    Any idea what is wrong?



  12. Unknown User (andreasg)

    Hi Pavel, thank you for maintaining this plugin.
    Maybe I missed something but we have issues with "Build PR targeting only these branches"

    PR are building fine until we try to add a branch name here. For example we would like to have different builds based on branch names like
    feature/XXX-1234-android-xxxxx 
    feature/XXX-1235-ios-xxxxx  
    I tried to add in targeting branch name: "android" ".*android.*" "feature/.*android" with no success. Can you help me what am I missing here to make this pugin build only the android branches?

    Thank you in advance. 

    1. Unknown User (proski)

      I don't maintain this plugin. This is a wrong please to ask support questions. Please ask on gitter: https://gitter.im/jenkinsci/stash-pullrequest-builder-plugin

  13. Unknown User (a3223351)

    Hi, Unknown User (proski) , I'm use this plugin(version 1.8) for my  jenkins(version 2.172)and Bitbucket server(version 5.6.1),but it's not work,problems are as follows:

    1、Bitbucket server's webhook do not trigger jenkins build the job.

    2、I have this error when I manually build the job.

    stderr: fatal: Couldn't find remote ref refs/heads/${sourceCommitHash}

    It seems that Jenkins did not use this variable “${sourceCommitHash}” correctly.

    can you help me? Thank you!

    1. Unknown User (proski)

      We don't have a designated support person for this plugin. Everybody who has time and knowledge can help you. I don't think it's a good place to triage issues here in the comments. There is a gitter page for the plugin, please try asking there. https://gitter.im/jenkinsci/stash-pullrequest-builder-plugin