Document where authentication credentials are stored

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.

@raiskila

@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!

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!

@mislav

@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 🙇

@cored

@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.

Where would you like that directory to be?

@cored

@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.

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.

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

For this bit specifically, see #449

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.

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?

@kyle-rader

@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.

@vilmibm

@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?

@kyle-rader

@kyle-rader correct.

@jsoref

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.

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.

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

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.

where does gh auth token get its token? none of these files contain the key:

]$ strace -f gh auth token 2>&1 | grep open
openat(AT_FDCWD, "/sys/kernel/mm/transparent_hugepage/hpage_pmd_size", O_RDONLY) = 3
[pid 2175448] openat(AT_FDCWD, "/usr/bin/gh", O_RDONLY|O_CLOEXEC) = 3
[pid 2175448] openat(AT_FDCWD, "/etc/localtime", O_RDONLY) = 3
[pid 2175448] openat(AT_FDCWD, "/home/user/.config/gh/config.yml", O_RDONLY|O_CLOEXEC) = 3
[pid 2175448] openat(AT_FDCWD, "/home/user/.config/gh/hosts.yml", O_RDONLY|O_CLOEXEC) = 3

Tokens are stored in the keychain as of #449

So tokens are not stored as plain text in a config file, but running gh auth token will still display it?

Assuming e. g. some package manager's install script wants to collection system information, the keychain-based storage does not help, right? Or is the token being displayed a short-lived one?

Navigation Menu

Repository navigation

Document where authentication credentials are stored #1773

Describe the feature or problem you’d like to solve

Proposed solution

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Document where authentication credentials are stored #1773

Description

Describe the feature or problem you’d like to solve

Proposed solution

Activity

mislav commented on Sep 18, 2020

raiskila commented on Sep 18, 2020

cored commented on Oct 28, 2020

samcoe commented on Oct 29, 2020

eacp commented on Dec 10, 2020

mislav commented on Dec 10, 2020

alexttx commented on Sep 8, 2021

gibfahn commented on Dec 27, 2021

jsoref commented on Apr 1, 2022

kyle-rader commented on Feb 26, 2023

vilmibm commented on Mar 1, 2023

kyle-rader commented on Mar 3, 2023

vilmibm commented on Mar 3, 2023

prggTheProgrammer commented on Apr 24, 2023

ssbarnea commented on Jan 12, 2024

jsoref commented on Jan 12, 2024

riywo commented on Aug 21, 2024

KJ7LNW commented on May 28, 2025

gibfahn commented on May 31, 2025

mpdude commented on Sep 24, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions