Sourcegraph extensions

Building an extension? See extension authoring documentation.

Sourcegraph extensions enhance your code host, code reviews, and Sourcegraph itself by adding features such as:

  • Code intelligence (go-to-definition, find references, hovers, etc.)
  • Test coverage overlays
  • Links to live traces, log output, and performance data for a line of code
  • Git blame
  • Usage examples for functions

When these features are built as Sourcegraph extensions, you get them everywhere you view and review code:

Extensions can provide the following functionality:

  • Go to definition
  • Find references
  • Hovers
  • Line decorations and annotations
  • Toolbar buttons
  • Commands
  • Search keywords

Screenshots of test coverage and Git blame extensions:

If you’ve used Sourcegraph before, you’ve used a Sourcegraph extension. For example, try hovering over tokens or toggling Git blame on tuf_store.go. Or see a demo video of code coverage overlays. These features (and many others) are provided by extensions. You could improve these features, or add new features, just by improving or creating extensions to Sourcegraph.

The Sourcegraph.com extension registry lists all publicly available extensions.

Usage

To view all available extensions on your Sourcegraph instance, click User menu > Extensions in the top navigation bar. (To see recommended extensions, click Explore in the top navigation bar.)

To enable/disable an extension for yourself, click User menu > Extensions, find the extension, and toggle the slider.

After enabling a Sourcegraph extension, it is immediately ready to use. Of course, some extensions only activate for certain files (e.g., the Python extension only adds code intelligence for .py files).

On your code host

Install the browser extension and point it to your Sourcegraph instance (or Sourcegraph.com) in its options menu. It will consult your Sourcegraph user settings and activate the extensions you’ve enabled whenever you view code or diffs on your code host or review tool.

For organizations

To enable/disable an extension for all organization members, add it to the extensions object in organization settings (as shown below).

{
  ...,
  "extensions": {
    ...,
    "alice/myextension": true, // or false to disable
    ...
  },
  ...
}

For all users

On a self-hosted Sourcegraph instance, add the same JSON above to global settings (in Site admin > Global settings).

Authoring

Ready to create your own extension? See the extension authoring documentation.

For inspiration:

Administration

Site administrators can customize how Sourcegraph extensions are used on their instance, with options for:

  • a private extension registry on their instance
  • allowing only specific extensions to be enabled by users
  • preventing users from enabling any extension from Sourcegraph.com

See “Administration of Sourcegraph extensions and the extension registry”.

Data, security and privacy

You can use Sourcegraph extensions without a Sourcegraph.com account or self-hosted Sourcegraph instance.1 To do so, just install the browser extension.

We designed Sourcegraph extensions with security and privacy in mind:

  • Extensions do not send your code to Sourcegraph to operate. They run entirely on the client in your web browser.
  • Extensions don’t have direct access to private code. Extensions needing code access, such as to provide find-references in a project, must fetch code from the API of your code host or self-hosted Sourcegraph instance. This requires you to explicitly permit access (e.g., by creating a GitHub access token and configuring the extension to use it).
  • Extensions run in isolation from your code host’s web pages. They don’t have direct DOM access (because they run in a Web Worker) and can only contribute actions and behavior allowed by the Sourcegraph extension API.
  • Extensions are sandboxed by your web browser. Because Sourcegraph extensions run inside of the Sourcegraph for Chrome/Firefox browser extension, they are limited by the permissions you granted to the browser extension.
  • Sourcegraph development is open source, so these claims are verifiable.

1 To use extensions other than the default set of language extensions, you currently do need an account or self-hosted instance. We plan to remove this limitation in Feb 2019.

More information

See “Principles of extensibility for Sourcegraph” for or more information about why we built the Sourcegraph extension API—and how it’s different from other attempts, such as LSP (Language Server Protocol).

See the Sourcegraph roadmap for future plans related to extensions.

Feedback

File bugs, feature requests, extension API questions, and all other issues on sourcegraph/sourcegraph.