Document where authentication credentials are stored

[raiskila]

Describe the feature or problem you’d like to solve

I can't find any information on the website or in the CLI help command about where authentication information is stored.

Proposed solution

Document where GH CLI stores authentication credentials. Also explain the relationship of this with existing GitHub credentials you may have on your system, like an SSH key or git https credentials in the keychain.

This helps the user understand the security and practical implications of logging in to the CLI.

[mislav]

@raiskila Have you tried gh auth status?

$ gh auth status
github.com
  ✓ Logged in to github.com as mislav (~/.config/gh/hosts.yml)
  ✓ Git operations for github.com configured to use https protocol.

The authentication credentials are stored in ~/.config/gh/hosts.yml.

Good points about documentation; thank you!

[raiskila]

Thanks for pointing that out, I was on 0.9.0 due to outdated Homebrew formulas and gh auth status was missing.

Yeah, this was mostly about the documentation, but I'm glad the information is also available there!

[cored]

@mislav Hi there, I was taking a look at this issue but I couldn't find where the documentation should be. I am guessing https://cli.github.com/manual/gh_auth_status here but even if that's the right place I don't see where or how the project is generating the documentation. If you could point me in the right direction I can help out with the change. Thanks 🙇

[samcoe]

@cored Our documentation pages are autogenerated by spf13/cobra during our release workflow. As for where we actually want this documentation to be placed I think we should wait for @mislav to chime in on that.

[eacp]

Where would you like that directory to be?

[mislav]

@cored @eacp All the implementation for gh commands, such as gh auth status, is under pkg/cmd/; e.g. pkg/cmd/auth/status/status.go. You will find the documentation for the command there that is also used to generate the man page.

[alexttx]

Please document clearly where sensitive information is stored, and whether or not it is stored in plain text form. For example, it appears .config/gh/hosts.yml contains sensitive authentication tokens that should be protected.

[gibfahn]

For example, it appears .config/gh/hosts.yml contains sensitive authentication tokens that should be protected.

For this bit specifically, see #449

[jsoref]

Fwiw, I'd expect to be able to find the information by looking here: https://cli.github.com/manual/gh_config

Remember, users don't know a system when they're looking for answers. The actual answer can be stored in gh status, but it'd be really valuable to include a see also reference from gh config.

[kyle-rader]

Related question: It is unclear to me if trying to configure SSH auth is going to wipe-out my existing ssh authentication for Git. I already have an ssh key generated, and uploaded to Github, but the gh auth login command seems to ignore that there's already a key there and still wants to log in via web browser.

Does this warrant a new issue specifically to allow using existing ssh configurations?

[vilmibm]

@kyle-rader gh is trying to log in via a web browser in order to get an oauth token it can use to call the GitHub API; it's a different authentication than the SSH key used for git operations. If you answer "no" to gh setting up git auth for you and select ssh as your preferred git protocol, your existing SSH key will continue to work normally for git operations.

[kyle-rader]

@vilmibm thanks for clarifying Nate, this makes sense. I take it github just doesn't support ssh auth for their web api? Only the git endpoints?

[vilmibm]

@kyle-rader correct.

[prggTheProgrammer]

Fwiw, I'd expect to be able to find the information by looking here: https://cli.github.com/manual/gh_config

@jsoref, I think it would also make sense to put the information in gh auth login. Because this command is what is storing the credentials. I think it should also explain the config it is doing or point to gh auth setup-git. Because it would explain better how credentials are stored, because they are stored using a credential manager. And also (but this is more another issue) gh auth setup-git doesn't explain what it is setting up:

This command configures git to use GitHub CLI as a credential helper. For more information on git credential helpers please reference: https://git-scm.com/docs/gitcredentials.

I think it should explain what it is changing in .gitconfig. For example will it automatically configure your email and username with your github's account details? (see #4351 (comment)) I don't think so, but it doesn't explain it anywhere.

[ssbarnea]

I wonder if there is an way to ask gh to report credentials (token) for a specific server. I am writing a python tool that uses github api to perform some tasks and re-using authentication from gh makes it easier for users instead of adding another place to store credentials.

[jsoref]

https://cli.github.com/manual/gh_auth_token

[riywo]

I think gh respects several environment variables so that the exact location varies: https://cli.github.com/manual/gh_help_environment

So, I guess mentioning the possibility of storing credentials inside the config dir on the document above would be helpful.