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 connect Phabricator to Sourcegraph:

  1. Go to Site admin > Manage repositories > Add repositories
  2. Select Phabricator.
  3. Configure the connection to Phabricator using the action buttons above the text field, and additional fields can be added using Cmd/Ctrl+Space for auto-completion. See the configuration documentation below.
  4. Press Add repositories.

Repository association

Sourcegraph can provide users with links to various Phabricator pages (for files, commits, branches, etc.) if you add Phabricator as a connection (in Site admin > Manage repositories).

A Phabricator 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"
  // ...
}

The site admin should also set alerts.codeHostIntegrationMessaging in global settings to ensure informational content for users in the Sourcegraph webapp references the native integration and not the browser extension.

{
  // ...
  "alerts.codeHostIntegrationMessaging": "native-integration"
  // ...
}

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"
}