Support multiple accounts on a single host

[williammartin]

Description

This PR is best understood by reading https://github.com/cli/cli/blob/c243f31a6ca2571b9e536c9d6cdd308ded51f4f5/docs/multiple-accounts.md

The summary is that we are adding support for authenticating against multiple accounts on a single host.

This work has been paired on by @samcoe and myself, with some asynchronous review.

[andyfeller]

All in all, that is massive amount of effort as I expected! Aside from a nit and a suggestion for extra usage doc for gh auth switch with GH_TOKEN set, I've got nothing else to really contribute.

[andyfeller]

I take it this is intended to be more meaningful as its possible even more so now that a user has multiple accounts with tokens, which was true being logged into GHES and GHEC.

[williammartin]

Well, previously there could only be one Token per hostname. Now it's intended to be meaningful because there is only one active one at a time (the one that is used for any API operations or as provided by the credential helper).

[andyfeller]

This behavior should be documented as I don't know if others would consider it. In the case you are using a GitHub App user access token for GH_TOKEN, should this still error?

[williammartin]

So firstly, this shouldn't really ever be hit because the Switch command protects against this already but I wanted to be defensive here in case it happens in future.

The switch command here acts the same as it does for login and logout which have exactly the same check. The idea is that if your token for a host is coming from the environment then we should be pretty suspicious of the user trying to make changes to their authorization set up because there's a good chance they are doing something surprising e.g. expecting that after logging in they are acting as someone else but it turns out it's coming from the env var.

I could go either way on this behaviour across all the commands but since it was in the others it felt sensible to include here.

[andyfeller]

Should this include a line about how switching when GH_TOKEN is set will cause an error?

[williammartin]

If you want but then we should mirror it for login and logout

[andyfeller]

How does this version read? Leaving diving into the nuances in subsequent sections, I hope this can give a high-level summary that people can get the gist.

Suggested change

	Since its creation, `gh` has enforced a mapping of one account per host. Functionally, this meant that when targeting a
	single host (e.g. github.com) each `auth login` would replace the token being used for API requests, and for git
	operations when `gh` was configured as a git credential manager. Removing this limitation has been a [long requested
	feature](https://github.com/cli/cli/issues/326), with many community members offering workarounds for a variety of use cases.
	A particular shoutout to @gabe565 and his long term community support for https://github.com/gabe565/gh-profile in this space.
	With the release of `v2.40.0`, `gh` has begun supporting multiple accounts for some use cases on github.com and
	in GitHub Enterprise. We recognise that there are a number of missing quality of life features, and we've opted
	not to address the use case of automatic account switching based on some context (e.g. `pwd`, `git remote`, etc).
	However, we hope many of those using these custom solutions will now find it easier to obtain and update tokens (via the standard
	OAuth flow rather than as a PAT), and to store them securely in the system keyring managed by `gh`.
	We are by no means excluding these things from ever being native to `gh` but we wanted to ship this MVP and get more
	feedback so that we can iterate on it with the community.
	With the `v2.40.0` release, [multi-account support](https://github.blog/changelog/2023-11-03-multi-account-support-on-github-com/) is introduced to `gh` for GitHub.com and GitHub Enterprise and it is only the beginning!
	Thanks to @gabe565 for his efforts to support multi-account capabilities with [`gh-profile` extension](https://github.com/gabe565/gh-profile) for this [long requested feature](https://github.com/cli/cli/issues/326)! ❤️
	This release focuses on several specific use cases:
	- adding multiple accounts for GitHub.com and GitHub Enterprise with `gh auth login`
	- switching manually between accounts for `gh` and `git` use with `gh auth switch`
	- seeing multiple accounts with `gh auth status`
	- logging out of accounts with `gh auth logout`
	Future enhancements such as automatic account switching based on contexts and more are possible based upon user feedback!

Really want to link "user feedback" to where people can click a link and leave said feedback.

[williammartin]

So, the tone of your suggested edits feels like release notes to me, and I think that it does a good job at that. However, I don't see this document as release notes but more a deep dive for the reader who wants more precision in what has actually changed.

How would you feel if we took your suggestion and used it in the release notes (and included a link to the release discussion for feedback), linking to this document?