This plugin provides Phabricator integration with Jenkins. It allows Jenkins to report build status and coverage information over Harbormaster (or via comments if Harbormaster is not enabled).
Before the plugin can be used, a few configuration steps on your Phabricator and Jenkins instances need to be completed.
In this section, you'll create a bot user in Phabricator and generate a Conduit API token. If you already have a bot user and a Conduit API token, skip to the "Jenkins Setup Section".
- Create a bot user in Phabricator.
- Click Edit Settings on the manage page for that user
- Click Conduit API Tokens on the left of the settings page
- Click Generate API Token, and accept.
- Copy the token.
- Navigate to
https://ci.example.com/configure
with your base Jenkins URL in place of "ci.example.com". - Navigate to the Phabricator section and click the Add button.
- From the Kind dropdown, select Phabricator Conduit Key.
- Enter the base URL for your Phabricator instance in the Phabricator URL field. For example
https://phabricator.example.com
. - Enter a description in the Description field for readability.
- Paste the Conduit API token (created in the Phabricator Configuration section) in the Conduit Token field.
- Click the Add button.
- Click the Save button.
Now that Jenkins and Phabricator are configured you can configure your Jenkins job and Harbormaster.
- Navigate to the Jenkins job you want to integrate with Phabricator.
- Click the Configure button.
- Click the Add Parameter button and select String Parameter.
- Enter
DIFF_ID
in the Name field of the parameter. - Repeat step 3.
- Enter
PHID
in the Name field of the second parameter. - If you want to apply the differential to your workspace before each test run, navigate to the Build Environment section and select the Apply Phabricator Differential checkbox. This resets to the base commit the differential was generated from. If you'd rather apply the patch to master, select the Apply patch to master checkbox.
- To report the build status to Phabricator after the test completes:
- Navigate to the Post-build Actions section.
- Click the Add post-build action button and select Post to Phabricator.
- Make sure the Comment on Success and Comment with console link on Failure checkboxes are selected.
- Optionally:
1. If you have Uberalls enabled, enter a path to scan for Cobertura reports.
2. If you want to post additional text to Phabricator other than "Pass" and "Fail", select the Add Custom Comment checkbox. Then create a
.phabricator-comment
file and enter the text you want Jenkins to add to the build status comment in Phabricator.
With Phabricator, Jenkins, and your Jenkins jobs configured it's time to configure a new Harbormaster build plan. This build plan will trigger the Jenkins job using a Herald rule that will be configured in the next section.
-
Navigate to
https://phabricator.example/harbormaster/plan/
with your base Phabricator URL in place ofphabricator.example
. -
Click the New Build Plan button in the top right corner of the page.
-
Enter a name for the build plan in the Plan Name field. For these instructions, we'll use "test-example" as the build name.
-
Click the Create Build Plan button.
-
Click the Add Build Step button.
-
Click the Make HTTP Request step.
-
Use this template URI to fill in the URI field for the build plan:
https://ci.example.com/buildByToken/buildWithParameters?job=test-example&DIFF_ID=${buildable.diff}&PHID=${target.phid}
Be sure to replace
https://ci.example.com
with the URI of your Jenkins instance andtest-example
with the name of your Jenkins job.If your Jenkins instance is exposed to the internet, make sure to install the Build Token Root Plugin and fill in the
token
parameter.
- Click the When Complete dropdown menu and select Wait For Message.
- Click the Create Build Step button.
With the build plans created it's time to create a Herald Rule to trigger the plans. The steps below will configure a Herald Rule to trigger the build plans on Differential Revisions to your repository.
- Navigate to
https://phabricator.example/herald/
with your base Phabricator URL in place ofphabricator.example
. - Click the Create Herald Rule button in the top right corner of the page.
- Select the Differential Revisions checkbox and click Continue.
- Select the Global checkbox and click Continue.
- Enter a name for the Herald Rule in the Rule Name field.
- In the Conditions section, click the dropdown menu that says "Author" and select "Repository".
- Enter your repository name in to the blank field in the Conditions section.
- In the Actions section, click the dropdown menu that says "Add blocking reviewers" and select "Run build plans".
- Enter the build plans that were created in the previous section in to the blank field in the Action section.
- Click Save Rule.
Try arc diff
-ing on your repo. If everything goes well, you should see Jenkins
commenting on your diff:
Now that you have build status and optionally coverage data set up, check out some advanced features.
Set up your Maven file according to https://wiki.jenkins-ci.org/display/JENKINS/Plugin+tutorial.
Start up Jenkins with the plugin installed:
mvn hpi:run
Open your browser to your local instance.
Please open all pull requests and issues against https://github.com/uber/phabricator-jenkins-plugin.
MIT Licensed