skip to content

With the GitHub CLI, what does gh auth setup-git change in Git's configuration, and which token does git push then send?

level: middleimportance: should knowfreq 26%

answer

  1. Git asks a helper program
  2. global config, one entry per host
  3. an empty value first
  4. HTTPS only, never SSH
  5. the active account's token

basics

~20 s

gh auth setup-git adds a per-host credential helper to the global Git config, running gh auth git-credential after an empty entry that clears earlier helpers. HTTPS Git requests then get gh's own token: an environment token or the host's active account.

solid answer

~50 s

For every authenticated host (or only `--hostname`), `gh auth setup-git` runs `git config --global` to set `credential.https://<host>.helper` to an empty value, which discards helpers Git collected earlier for that URL, and then adds `!<path-to-gh> auth git-credential`; on github.com it does the same for the gist host. When Git needs HTTPS credentials it calls that helper, and gh answers with the token it would use itself: an environment token first, otherwise the host's active stored account. The username is the account's login, or `x-access-token` for an environment token. gh answers only for `https`, so SSH remotes are untouched, and it ignores Git's `store` and `erase` requests, so a failed push never logs gh out. Because the lookup happens on every request, `gh auth switch` or `gh auth refresh` changes what Git sends next without reconfiguring anything.

code

bash · 4 lines
bash
gh auth setup-git --hostname ghe.example.com
git config --global --get-all credential.https://ghe.example.com.helper
#
# !/usr/local/bin/gh auth git-credential

go deeper

for a junior

Know that gh auth setup-git lets git push over HTTPS reuse the account you logged in to with gh, so you never create a separate password for Git.

for a middle

Explain the global per-host helper entry, the empty value that resets the chain, and that gh answers with the active or environment token only for HTTPS.

for a senior

Debug pushes that use the wrong identity: check which helper Git calls for that URL, which account is active in gh, whether an environment token overrides it, and whether the remote is SSH.

for a principal

Decide whether developer machines should rely on one global helper tied to an active account, or keep per-identity setups where people routinely work for several organisations.

## The problem it solves Over HTTPS, Git authenticates with a username and a password, and GitHub accepts a **token** as the password. Git does not have to ask a person for them: it can call a **credential helper**, a program that returns credentials on request (how helpers work in general is Git's own subject). `gh auth setup-git` makes the GitHub CLI that program for the hosts gh is logged in to, so `git clone`, `fetch` and `push` reuse gh's token and there is no second credential to create, store and rotate. ## What the command writes For each authenticated host — or only the one given with `--hostname` — gh edits your **global** Git configuration (`git config --global`): 1. It sets `credential.https://<host>.helper` to an **empty value** with `--replace-all`. To Git, an empty helper value means "forget the helpers collected so far for this URL", so a helper configured earlier, such as an old cached password, is not consulted first. 2. It adds `credential.https://<host>.helper` with the value `!<path-to-gh> auth git-credential`. The leading `!` tells Git to run the rest as a shell command; the path is the gh executable that ran the setup. 3. On github.com it repeats both steps for the gist host, so gists cloned over HTTPS authenticate too. With no authenticated host the command fails with an error. `--hostname` for a host gh is not logged in to also fails, unless `--force` is added, and `--force` is accepted only together with `--hostname`. ## What happens on a push 1. Git needs credentials for `https://ghe.example.com/acme/api.git` and calls the helper with the `get` operation. 2. gh's hidden `auth git-credential` command reads the request and answers only when the protocol is `https`. 3. It looks up the token for that host by the same rules every gh command follows: an environment variable first (`GH_TOKEN` for github.com and ghe.com hosts, `GH_ENTERPRISE_TOKEN` for Enterprise Server hosts), otherwise the host's **active** stored account. 4. It replies with a `username` and `password`: the stored account's login, or `x-access-token` when the token came from a variable. 5. Git sends them. The `store` and `erase` requests Git issues after success or failure are accepted and deliberately ignored, so a rejected push never makes Git log gh out. | Situation | What Git receives from gh | |---|---| | Logged-in account, HTTPS remote | the active account's login and its token | | `GH_TOKEN` set, github.com remote | `x-access-token` and the variable's token | | SSH remote (`git@...` URL) | nothing — the SSH key authenticates instead | | A host whose gh login was removed | nothing, so Git falls back to asking for credentials itself | ## How it ties into the rest of `gh auth` - During an interactive `gh auth login` with HTTPS, answering yes to **"Authenticate Git with your GitHub credentials?"** installs gh's helper only when Git has no helper for that host yet. If one is already configured, gh hands the new token to that existing helper instead — and that copy does not follow later `gh auth switch` or `refresh`. `gh auth setup-git` installs gh's own helper either way. - When Git is going to use gh's token — gh is already the helper, or you answer yes to that prompt — the login also requests the **`workflow`** scope, so that pushes which change workflow files are not rejected for a missing scope. - `gh auth switch` changes a host's active account, and with it the token Git receives on its next request; `gh auth refresh` replaces the token the same way. Neither needs `setup-git` to be run again. - `git_protocol` is a separate, per-host gh setting. It decides the URLs gh uses when it clones for you; it does not change remotes that already exist. ## Pitfalls worth knowing - **It is global.** Every repository you use on that host authenticates as gh's active account; gh does not pick an identity per directory. - **It records a path.** The helper entry contains the location of the gh executable, so after reinstalling gh somewhere else, run `gh auth setup-git` again or Git will call a program that no longer exists. - **It does not set commit identity.** `user.name` and `user.email` remain Git's own settings; authenticating as one account does not change who commits are attributed to. - **Uninstalling gh** should include removing these entries, for the same reason.

  • Why does gh write an empty helper value before its own entry?
    Git consults every configured helper in order, and an empty value resets that list. Clearing it first means gh's token is the one offered for that host, instead of a stale password another helper cached before gh was installed.
  • Your remote uses SSH. Does gh auth setup-git change how git push authenticates?
    No. gh's helper answers only `https` requests, and an SSH remote never asks a credential helper; the SSH key decides. To move a clone to gh's token, change its remote URL to HTTPS, or set `git_protocol` to `https` so future gh clones use HTTPS.

gh as Git's helper works like a hotel front desk that cuts you the key for the room currently on your booking each time you ask, instead of a key you copied once: change the booking with gh auth switch and the next key Git receives opens the new room.

  • gh auth setup-git stores a copy of the token inside the Git config
  • The gh credential helper also authenticates SSH remotes
  • After gh auth switch you must run gh auth setup-git again
  • A failed push makes Git erase gh's stored login
  • setup-git sets user.email to the account's address