Phabricator

Site admins can associate Git repositories on Phabricator with Sourcegraph so that users can jump to the Phabricator repository from Sourcegraph and use the Phabricator extension and browser extension with Phabricator.

To set this up, add Phabricator as an external service to Sourcegraph:

  1. Go to User menu > Site admin.
  2. Open the External services page.
  3. Press + Add external service.
  4. Enter a Display name (using “Phabricator” is OK if you only have one Phabricator instance).
  5. In the Kind menu, select Phabricator.
  6. Configure the connection to Phabricator in the JSON editor. Use Cmd/Ctrl+Space for completion, and see configuration documentation below.
  7. Press Add external service.

Repository association

Sourcegraph can provide users with links to various Phabricator pages (for files, commits, branches, etc.) if you add Phabricator as an external service (in Site admin > External services).

A Phabricator external service configuration consists of the following fields:

  • url field that maps to the url of the Phabricator host
  • token an optional Conduit API token, which you may generate from the Phabricator web interface. The token is used to fetch the list of repos available on the Phabricator installation
  • repos if your Phabricator installation mirrors repositories from a different origin than Sourcegraph, you must specify a list of repository paths (as displayed on Sourcegraph) and their corresponding Phabricator callsigns. For example: [{ path: 'gitolite.example.org/foobar', callsign: 'FOO'}]. Note that the callsign is case sensitive.

At least one of token and repos should be provided.

For example:

{
  // ...
  "phabricator": [
    {
      "url": "https://phabricator.example.com",
      "token": "api-abcdefghijklmnop",
      "repos": [{ "path": "gitolite.example.com/mux", "callsign": "MUX" }]
    }
  ]
  // ...
}

See configuration documentation below for more information.

Troubleshooting

If your outbound links to Phabricator are not present or not working, verify your Sourcegraph repository path matches the “normalized” URI output by Phabricator’s diffusion.repository.search conduit API.

For example, if you have a repository on Sourcegraph whose URL is https://sourcegraph.example.com/path/to/repo then you should see a URI returned from diffusion.repository.search whose normalized field is path/to/repo. Check this by navigating to $PHABRICATOR_URL/conduit/method/diffusion.repository.search/ and use the “Call Method” form with attachments field set to { "uris": true } and constraints field set to { "callsigns": ["$CALLSIGN_FOR_REPO_ON_SOURCEGRAPH"]}. In the generated output, verify that the first URI has a normalized path equal to path/to/repo.

Native extension

For production usage, we recommend installing the Sourcegraph Phabricator extension for all users (so that each user doesn’t need to install the browser extension individually). This involves adding a new extension to the extension directory of your Phabricator instance.

See the phabricator-extension repository for installation instructions and configuration settings.

The Sourcegraph instance’s site admin must update the corsOrigin site config property to allow the Phabricator extension to communicate with the Sourcegraph instance. For example:

{
  // ...
  "corsOrigin":
    "https://my-phabricator.example.com"
  // ...
}

Configuration

admin/external_service/phabricator.schema.json

{
	// The list of repositories available on Phabricator.
	"repos": null,

	// API token for the Phabricator instance.
	"token": null,

	// URL of a Phabricator instance, such as https://phabricator.example.com
	"url": null
	// Other example values:
	// - "https://phabricator.example.com"
}