Authenticate GitHub CLI and Git Safely with gh auth

One gh auth command logs you in, another quietly switches your active account, and mixing them up is how a pull request lands under the wrong name. This guide gets you an authenticated GitHub CLI account, a verified host and account selection, and Git configured to ask gh for credentials when needed. The examples match GitHub CLI 2.87.3, installed here as Ubuntu package gh 2.45.0-1ubuntu0.3+esm3; the package and binary report different version strings, so check your own system if exact behaviour matters.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Log in through the browser flow
3. Verify the host and active account
4. Configure Git to use gh
5. Handle multiple accounts deliberately
6. Refresh scopes only when required
7. Log out or recover from a mistake

Allow about ten minutes for a normal browser login. You need a shell and access to the GitHub host you intend to use. No command here needs sudo. Login, account switching, scope changes and logout all alter local authentication state, so read the warning before each of those steps.

1. Check the installed command

Start with read-only checks. Neither contacts GitHub nor changes credentials:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth --help
Authenticate gh and git with GitHub

The command family is gh auth, with the useful subcommands login, status, setup-git, switch, refresh, token and logout. The default host is github.com, but every enterprise example should name its host explicitly.

Checkpoint

If gh --version fails, stop here. Install or repair GitHub CLI through your normal package-management process; do not try to authenticate with a different binary by accident.

2. Log in through the browser flow

For the usual interactive login, run:

$ gh auth login
? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials? Yes

The prompts and final messages depend on the installed version and your terminal. Login is a browser-based flow by default, and the completed token lands in the system credential store when one is available.

Warning

If no usable credential store is found, gh can fall back to a plain-text token file. Check gh auth status and protect the reported location with your operating system's normal account permissions.

For an Enterprise Server host, give the hostname rather than relying on the default:

$ gh auth login --hostname github.example.com

Choose --git-protocol ssh only when SSH keys and repository URLs are part of your intended setup; the SSH path may offer to create and upload a key. --git-protocol https keeps repository transport on HTTPS and is often the simpler first choice.

Warning

Never paste a real token into an article, terminal transcript or shell history. --with-token reads a token from standard input, but the manpage recommends GH_TOKEN for fine-grained tokens in headless use. Prefer the browser flow on an interactive workstation.

3. Verify the host and active account

Ask gh to test the stored authentication. This is another ordinary command:

$ gh auth status --active --hostname github.com
github.com
  ✓ Logged in to github.com account EXAMPLE_USER
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: *******************
  ✓ Token scopes: gist, read:org, repo

Usernames, protocol text and token scopes vary. A successful command normally exits zero; if an account has an authentication issue, the non-JSON form exits 1 and reports the problem on standard error. Add --hostname so a second host does not distract you while diagnosing the first.

Warning

Do not use --show-token during routine checks. It prints the credential in plain text and may expose it to terminal logs, screen sharing or process capture. If a token has been exposed, revoke the affected authorisation in GitHub settings and log in again.

4. Configure Git to use gh

Successful gh authentication does not automatically configure every Git client. Apply the credential-helper change after checking the login:

$ gh auth setup-git
✓ Configured git protocol
✓ Logged in to github.com account EXAMPLE_USER

By default this configures GitHub CLI as the credential helper for all authenticated hosts. To limit the change to one host:

$ gh auth setup-git --hostname github.example.com

Checkpoint

Inspect the relevant Git configuration without printing a token:

$ git config --show-origin --get-regexp 'credential\..*helper|credential\.helper'
file:/home/EXAMPLE_USER/.gitconfig	credential.helper=!gh auth git-credential

The path, helper form and scope can differ. If no host is authenticated, setup-git fails; fix authentication first. Adding --force does not create credentials and should only be used with an explicit --hostname when you understand the Git configuration you are changing.

5. Handle multiple accounts deliberately

gh can store more than one account per host. List the known accounts and the active selection:

$ gh auth status --hostname github.com
github.com
  ✓ Logged in to github.com account PERSONAL_USER (keyring)
  ✓ Logged in to github.com account WORK_USER (keyring)
  ✓ Active account: PERSONAL_USER

Switching changes which account commands use for that host, so make the choice explicit:

$ gh auth switch --hostname github.com --user WORK_USER
✓ Switched active account for github.com to WORK_USER
$ gh auth status --active --hostname github.com

With exactly two accounts, gh auth switch can switch automatically; with more than two, provide --user or use the prompt. To undo an accidental switch, run the same command with the previous account name.

6. Refresh scopes only when required

When a command needs an extra permission, refresh the active account rather than creating another login:

$ gh auth refresh --hostname github.com --scopes read:project

This starts another authentication flow and changes the stored credential's scopes. Use the smallest additional scope that solves the task. To remove an optional scope, make that change explicit too:

$ gh auth refresh --hostname github.com --remove-scopes delete_repo

The minimum set described by the installed help, repo, read:org and gist, cannot be removed by this command, and scope removal is idempotent. If you selected the wrong account, switch to the intended account first, refresh it, then switch back.

7. Log out or recover from a mistake

Logout removes the local authentication configuration for an account, but it does not revoke the token at GitHub:

$ gh auth logout --hostname github.com --user WORK_USER
✓ Logged out of github.com account WORK_USER

Warning

This is a state-changing action. If you only meant to stop using an account temporarily, switch to another account instead. To undo logout, run gh auth login --hostname github.com again. To revoke OAuth tokens generated by GitHub CLI, use GitHub's authorised applications settings; revoking all GitHub CLI tokens affects every device, not just this workstation.

Done means

Account identified cleanly. gh auth status --active --hostname HOST shows the intended account without exposing its token.
Enterprise hosts named explicitly. The host is always explicit for GitHub Enterprise Server.
Git helper scoped correctly. gh auth setup-git has configured only the hosts you intended.
Accounts switched deliberately. Multiple accounts are switched with an explicit username and can be switched back.
Scopes kept minimal. Additional scopes were requested only for a real requirement.
Logout versus revocation understood. Logout removes local configuration; revocation happens in GitHub settings.