Home / Alt manpages / gh-auth-setup-git(1)

  • gh-auth-setup-git(1)
  • User command
  • linux

Stop Retyping GitHub Passwords with gh auth setup-git

Typing your GitHub password for every git push gets old fast, and gh auth setup-git ends it for good. It wires Git to ask GitHub CLI for credentials on any host you have already authenticated, then you check exactly what changed. The examples below use GitHub CLI 2.87.3, installed here in February 2026. Allow about ten minutes.

The route

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

  • You need: gh, git, and an authenticated host, unless you deliberately use the force option for a host-specific setup.
  • It will not touch: your login state, any token, a repository remote, or your permissions. It only edits your user Git configuration. Keep that boundary in mind before you go troubleshooting a failed clone or push.

1. Check the installed commands

Start with read-only checks. None of these need elevated privileges:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ command -v git
/usr/bin/git
  • Paths and versions vary. Yours will differ from the example above, and that is fine.
  • Do not confuse the commands. gh auth setup-git wires the credential helper; gh auth login handles authentication itself.

Checkpoint

If gh --version fails, stop here and install or repair GitHub CLI through your normal package-management process. No Git configuration has been changed yet.

2. Check authentication for the host

For the usual GitHub host, ask GitHub CLI for the active account:

$ gh auth status --active --hostname github.com
github.com
  ✓ Logged in to github.com account YOUR_ACCOUNT
  - Active account: true
  - Git operations protocol: https
  - Token scopes: ...
  • Account and scopes are host-specific. The command can exit non-zero if authentication is absent or has a problem.
  • Skip the token flag. Do not use --show-token in a routine check: it prints a secret.
  • Enterprise host? Replace github.com with the real hostname, such as git.example.internal, matching the host your Git remote actually uses.

3. Configure the default authenticated hosts

Once authentication is confirmed, run:

$ gh auth setup-git

With no --hostname, GitHub CLI sets itself up as the credential helper for every authenticated host it knows about. A successful run normally produces no output and returns status 0. It writes a host-specific Git configuration entry whose helper command invokes gh auth git-credential.

It will not configure a host you have not authenticated. If nothing is authenticated, the command fails rather than guessing which host you meant. That is a useful stop signal, not a reason to bung a token into a random file.

4. Configure one host explicitly

Use --hostname when you want a single target, especially on a machine that knows several GitHub accounts or Enterprise hosts:

$ gh auth setup-git --hostname git.example.internal

The named host must already be authenticated, or the command fails. Confirm the spelling first:

$ gh auth status --active --hostname git.example.internal

Warning

Do not add sudo. This is a per-user Git configuration change, and running it as root configures root's Git instead of yours.

5. Use force only for a deliberate host entry

--force must be combined with --hostname. It lets you set up a host that GitHub CLI does not know about yet, but it does not authenticate that host or create credentials for it:

$ gh auth setup-git --hostname git.example.internal --force

Warning

Treat this as a security-sensitive step. Check the hostname character by character, and never apply it to a value copied from an untrusted URL or script. It is appropriate when you are preparing a known host and will provide authentication through the supported GitHub CLI environment or configuration afterwards.

6. Verify the Git helper without exposing credentials

Inspect the helper values for the host. This reads configuration only; it does not print a token:

$ git config --global --get-all 'credential.https://github.com.helper'
!/home/linuxbrew/.linuxbrew/bin/gh auth git-credential

The path is installation-specific. What matters is a shell helper ending in gh auth git-credential. Substitute your own hostname if you configured a different one. An empty result means the entry was not written at that scope, or the host key does not match the URL Git is using.

For a final functional check, use a repository you are authorised to access:

$ git -C /path/to/your/repository ls-remote origin HEAD
<commit-id>        HEAD

Checkpoint

The commit identifier will differ on your machine. This command contacts the remote but does not change it. A permission error means the account or token lacks access; a host mismatch means the configured hostname and remote URL need checking.

7. Undo one host entry safely

Before removing a helper, inspect the section and confirm it is the entry you actually mean to remove:

$ git config --global --get-regexp '^credential\.'
credential.https://github.com.helper !/home/linuxbrew/.linuxbrew/bin/gh auth git-credential

To remove the complete helper section for one HTTPS host, run the following with the real hostname:

$ git config --global --remove-section 'credential.https://github.com'

Warning

This removes the host-specific helper configuration, not the stored GitHub CLI login. If the section holds another helper you still need, do not remove it blindly. Record the existing values first and restore them through your normal Git configuration process.

Done means

  • Both commands resolve. gh --version and git both point at the commands you expect.
  • The host is authenticated. Unless you deliberately used --force while preparing a known host.
  • The helper is correct. The host-specific entry ends in gh auth git-credential.
  • A read-only check passes. git ls-remote succeeds against a repository you can access.
  • You know how to undo it. Removing the host section if this user-level configuration is no longer wanted.