User problem

Today, there are three ways to setup credentials for batch changes.

As a site admin setting up Sourcegraph and Batch Changes, I:

• Setup a codehost connection with a limited scope to use Search
• Then, later, if I want to setup Batch Changes, I need to
  • Setup a global service account
  • Or, add the read:org and read:discussion scopes to the codehost connection, then guide my users through adding one personal access token per user.

This results in confusion:

• There are multiple possible paths, and multiple steps that need to be accomplished by different user groups (site admin and user). Those steps are explained in a single docs page that both site-admin and users go to (or don't go to) and get lost.
• In-product error messaging, and setup in general, does not provide clear guidance. For example, a user might see the error message below, and assume that they need to increase the scope of the codehost connection to allow for changeset syncing. In fact, they need to add a PAT (or use a global service account).

Error in GraphQL response: Your token has not been granted the required scopes to execute this query. The 'name' field requires one of the following scopes: ['read:org', 'read:discussion'], but your token has only been granted the: ['repo'] scopes. Please modify your token's scopes at: https://github.com/settings/tokens.

Why now?

• This creates confusion for customers and the customer engineering team, and induces delays in trials and a degraded first impression (and they matter!).
• Tech debt (TBD)

Considerations

• Imported changesets: today, we have no connection between a changeset and a user at the data-model level. Since we don't know what user's PAT to use, we default to the code host connection token to sync imported changesets.
• We want to allow customers to either:
  • use batch changes with a shared service account with broad access, if their security model allows
  • or use per use credentials
  • later on, we'll likely have to support more complex credential models (eg. some users use a shared account, some their personal token).

Proposal

• Remove global code host connection (they have been deprecated since 3.27)
• Simplify the docs, to provide a clear path for users, and a clear path for site-admin
• Out of scope, potential follow-up Batch changes site admin configuration page #25400