Set Up Git Credential Handling with gh auth setup-git

You will configure Git to ask GitHub CLI for credentials when accessing an authenticated GitHub host, then verify exactly what changed. The examples use GitHub CLI 2.87.3, installed here in February 2026. Allow about ten minutes. You need gh, git, and an authenticated host unless you deliberately use the force option for a host-specific setup.

This command changes your user Git configuration. It does not log you in, create a token, change a repository remote, or grant extra permissions. Keep that boundary in mind before troubleshooting a failed clone or push.

1. Check the installed commands

Start with read-only checks. These do not 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

Your paths and patch version may differ. The relevant command is gh auth setup-git; do not confuse it with gh auth login, which 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: ...

The account name and scope list are host-specific. The command can exit non-zero if authentication is absent or has a problem. Do not use --show-token in a routine check: it prints a secret.

For a GitHub Enterprise Server host, replace github.com with a real hostname such as git.example.internal. The hostname must match the host used by your Git remote.

3. Configure the default authenticated hosts

Once authentication is confirmed, run:

$ gh auth setup-git

With no --hostname, GitHub CLI configures itself as the credential helper for all authenticated hosts 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 does not configure an unauthenticated host. If no hosts are authenticated, the command fails instead of guessing which host you meant. That is a useful stop signal, not a reason to add a token to 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. If it is unknown to GitHub CLI, the command fails. Confirm the spelling first:

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

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

5. Use force only for a deliberate host entry

--force must be combined with --hostname. It allows setup for a host that GitHub CLI does not know, but it does not authenticate that host or create credentials:

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

This is appropriate when you are preparing a known host and will provide authentication through the supported GitHub CLI environment or configuration later. Treat it as a security-sensitive configuration step: check the hostname character by character, and do not apply it to a value copied from an untrusted URL or script.

6. Verify the Git helper without exposing credentials

Inspect the helper values for the host. This reads configuration only and 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. The important part is a shell helper ending in gh auth git-credential. If you configured another host, substitute its exact hostname in the configuration key. An empty result means the entry was not written at that scope or the host key does not match the URL Git uses.

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

The commit identifier will differ. 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 make sure it is the entry you intend 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'

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