Skip to content

Improve usability around connecting code hosts with personal access tokens

Created by: quinnkeast

Problems

  1. Multiple users expected the link in the access token modal to take the user directly to the "Create new token" page, instead of a docs page. Then, the process of creating a personal access token is pretty painful, and ends up creating a lot of friction and back-and-forth between tabs at a moment we want users to build momentum.
  2. A concern arose over the language used in the subheading for the page, "Connect with providers where your code is hosted." Given that we're consistent with calling them "code hosts" in all other locations, this stands out as distinct and it's not clear why.
  3. We ran into a couple of cases where users tried to add their Enterprise GitHub or Gitlab connections instead of .com. This results in an opaque error, because an Enterprise token is going to fail like any other invalid token, and it won't be clear why it failed.
  4. If a user grants only public_repo scope for GitHub, we will have a messy situation around private repo availability in the future that will involve a lot of edge-case-handling.

Solutions

First, on GitHub, we should require repo scope, not just public_repo scope. This will prevent a lot of problems and case handling in the future, as we can catch and present an error in the context of the code host connections.

Second, we should adjust content in the access token modal to better highlight that it's for .com, rather than Enterprise, and update the link to directly link to the code host's new access token page, with the specific token pre-set (when available—GitHub definitely does let us do this, but I can't figure out a solution for GitLab).

GitHub: https://github.com/settings/tokens/new?scopes=repo GitLab: https://gitlab.com/-/profile/personal_access_tokens

CleanShot 2021-03-01 at 18 17 50@2x

Third, we should update the copy in the subheading to make the language consistent:

"Connect with your code hosts. Then, add repositories to search with Sourcegraph."

These changes are all up to date on the OAuth Code Host Connection details on Figma.