Skip to content

Add in-app hints / quick actions to configure native integrations

Created by: lguychard

Our Phabricator, Bitbucket Server and GitLab native integrations are great drivers of engagement when site admins enable them for all users on an instance. A good example of this is https://app.hubspot.com/contacts/2762526/company/464956351, or, more recently, https://app.hubspot.com/contacts/2762526/company/2931649618 (see https://sourcegraph.slack.com/archives/C0B2RU51Q/p1587673231447100).

In spite of this, the process of enabling native integrations has a lot of friction:

  • It is not directly encouraged from within the application (instead, we have the browser extension toast)
  • The level of quality for the documentation of our native integrations varies greatly: BitbucketServer is pretty good, but GitLab is very terse, and Phabricator leaves a lot to be desired.

We should:

  • Have in-app hints to enable the native integrations when a site admin adds a relevant external service (Bitbucket Server, Phabricator, GitLab). These should be shown right after the adding the external service, and should be added as an activation step if the site admin doesn't configure it right away.
  • Possibly provide relevant quick actions to help the site admin do this, such as:
    • Adding the code host's URL to corsOrigin
    • Linking directly to the plugins page on the Bitbucket Server instance, or to the settings page on the GitLab instance.
  • Link to the native integrations docs from the app, and improve them so that the site admin can easily understand:
    • What the integration is supposed to add to their code host instance
    • What the impact of the integration will be on their instance
    • How to easily troubleshoot common problems with native integrations (eg. authentication issues)

We should also investigate #8350, so that native integrations can be used on trial instances that may not have TLS set up.

We should dogfood these flows to make sure they're frictionless and easy to understand.