Phabricator Integration

Introduction

Phabricator is a powerful tool that can host your repositories, and can be used for code reviews. Phabricator comes with a CI tool in-built called Harbormaster. At your organization, you might use an external CI tool, such as CircleCI or Jenkins, however you will still need to make a Harbormaster step to use Screenshotbot.

At the end of this set up, you’ll have a screenshotbot user on Phabricator that will block any diffs that have screenshot changes, until the changes have been reviewed.

Phabricator Preparation

Screenshotbot will need a bot user to access Phabricator. As an Admin you can find this under People app:

We recommend naming the bot screenshotbot, but the name does not matter. At this point you’ll need the Conduit API Key, which we’ll use later in Screenshotbot.

Setting up Screenshotbot

Set up the Phabricator URL and the Conduit key on Screenshotbot from Settings.

Add a Harbormaster Build Plan

We'll create a "dummy" Harbormaster Build Plan. This build plan will not actually do much: it will just call a callback to Screenshotbot. Screenshotbot will push all the screenshot statuses as unit tests under this Build.

Open the Phabricator Harbormaster app (e.g. https://phabricator.example.com/harbormaster). Click the Manage Build Plans on your left, and then click the Create Build Plan on your top right. We'll now create a simple build, let's call it Screenshotbot.

Your Build Plan should have exactly one step, to make an HTTP request:

• The URI is: https://screenshotbot.io/phabricator/update-build?diff=${buildable.diff}&revision=${buildable.revision}&target-phid=${target.phid}&build-phid=${build.phid}
• HTTP Method: POST
• Credential: Create a new Password credential with the username as your Screenshotbot API Key, and password as your API secret
• When Complete: Wait For Message

Trigger the Harbormaster Build Plan on all diffs

You most likely already have a Herald rule to trigger builds on diff. Find this rule, and modify it to trigger the Screenshotbot Build Plan we just created. Here's what that Herald rule looks like on our Phabricator instance:

At this point, each time you create a diff you'll see a Screenshotbot Build that will never complete. In order to have that complete, you need to call the Screenshotbot CLI tool in one of your builds. (The order of the builds do not matter.)

Updating CI Step

Finally, we need to provide the Diff ID when calling the Screenshotbot CLI. The exact parameters depend on your platform (Android/iOS/Selenium). Let’s work with a specific example. Let’s say you’re using the Phabricator for Jenkins plugin. This plugin will set up the DIFF_ID parameter on your jobs, and the job will be triggered by Harbormaster.

In this case you can pass the additional argument to the CLI:

    ~/screenshotbot/recorder ...
            --phabricator-diff-id "$DIFF_ID"
            ...

If you're using DryDock for your builds, then you might have to prepend DIFF_ID=${buildable.diff} to your Drydock command.

Getting notifications on Phabricator

If you've set everything right, you'll now get notified on every Phabricator diff that has chanes. Accepting the changes, will turn the build to green. Rejecting the changes will turn the build to Red. You can accept or reject a report multiple times.