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.

⚠️ NOTE: Sourcegraph support of Phabricator is limited (learn more), and not expected to evolve due to the announced cease of support for Phabricator.

To connect Phabricator to Sourcegraph:

1. Go to Site admin > Manage code hosts > 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 code hosts).

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:

JSON
{
  // ...
  "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:

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

Configuration

admin/code_hosts/phabricator.schema.json

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

Configuration Notes

• Limited Support: Phabricator support is limited and not expected to evolve due to Phabricator's end-of-life announcement.
• Token vs Repos: At least one of token or repos must be provided. Use token for automatic discovery or repos for manual mapping.
• Case-Sensitive Callsigns: Repository callsigns are case-sensitive and must match exactly as configured in Phabricator.
• Repository Association: Sourcegraph creates links to Phabricator pages but doesn't sync the actual repository content from Phabricator.

Security Considerations

• API Token Management: Store Conduit API tokens securely and limit their scope to necessary operations.
• CORS Configuration: Update Sourcegraph's corsOrigin setting to allow the Phabricator extension to communicate with your instance.
• Network Access: Ensure Sourcegraph can reach your Phabricator instance over HTTPS.
• Token Rotation: Regularly rotate API tokens and update configurations accordingly.

Common Examples

Basic Configuration with Token

JSON
{
  "url": "https://phabricator.example.com",
  "token": "api-abcdefghijklmnop"
}

Manual Repository Mapping

JSON
{
  "url": "https://phabricator.example.com",
  "repos": [
    { "path": "github.com/myorg/frontend", "callsign": "FRONT" },
    { "path": "github.com/myorg/backend", "callsign": "BACK" }
  ]
}

Mixed Configuration

JSON
{
  "url": "https://phabricator.example.com",
  "token": "api-abcdefghijklmnop",
  "repos": [
    { "path": "gitolite.example.com/special-repo", "callsign": "SPEC" }
  ]
}

Best Practices

• Verify Repository Paths: Use Phabricator's diffusion.repository.search API to verify that Sourcegraph repository paths match normalized URIs.
• Test Native Extension: Install the native Phabricator extension for better user experience compared to browser extensions.
• Monitor Deprecation: Plan migration away from Phabricator due to its announced end-of-life status.
• Troubleshooting: Use the Conduit API testing interface to verify token permissions and repository accessibility.