Authenticate GitHub CLI and Git Safely with gh auth

You will finish with 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.

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 in this guide needs sudo. Login, account switching, scope changes and logout alter local authentication state, so read the warning before each of those steps.

1. Check the installed command

Start with read-only checks. They do not contact GitHub or change 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. Its useful subcommands are login, status, setup-git, switch, refresh, token and logout. The default host is github.com, but every host-specific example should name an enterprise host explicitly.

Checkpoint: if gh --version fails, stop here. Install or repair the 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. The default authentication mode is a browser-based flow, and the completed token is stored in the system credential store when one is available. If no usable credential store is found, gh can fall back to a plain-text token file. That fallback is a security boundary: check gh auth status and protect the reported location with the 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. The alternative --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 for 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 to prevent a second host from distracting you while diagnosing the first.

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

The exact output varies. By default, this configures GitHub CLI as the credential helper for all authenticated hosts. To limit the change to one host, use:

$ 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 for a host. List the known accounts and 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. It changes local authentication state, 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

If there are 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 additional 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. If you need to remove an optional scope, make that change explicit:

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

The minimum set described by the installed help, including repo, read:org and gist, cannot be removed by this command. 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.