gh auth login on a headless server
Updated · Jere & CO
Most CLI logins break on a headless box because the browser redirects to localhost on the wrong machine. The GitHub CLI mostly doesn’t have that problem. Its web login uses GitHub’s device flow, which GitHub’s own docs describe as meant for headless apps such as CLI tools: there’s no redirect back to the box at all. You type a short code on any device, and gh, on the box, polls GitHub until you’ve approved.
So the honest answer to “how do I run gh auth login on a headless server” is: run it, and finish it somewhere else.
1. The web login, finished on another device
- On the box, run this (without
--web, gh starts an interactive setup; choose the browser login when it asks):
gh auth login --web
- gh prints a one-time code and tries to open a browser. On a headless box there’s none to open; that’s fine.
- On your laptop or phone, go to
https://github.com/login/device, sign in, and enter the code. - Approve. gh notices within a few seconds and finishes.
The code is valid for 15 minutes, so there’s no rush. gh auth login --web --clipboard copies the code for you, which helps when gh runs on the machine you’re sitting at; over SSH that clipboard belongs to the box.
2. A token, when nobody will be there to type a code
For CI, scripts and agent boxes, skip the login and give gh a token:
export GH_TOKEN=github_pat_…
gh auth status
GH_TOKEN (or GITHUB_TOKEN, lower in precedence) is used for github.com and ghe.com subdomains, avoids the prompt, and takes precedence over anything stored earlier. The manual favours it for fine-grained personal access tokens. For GitHub Enterprise Server, the variable is GH_ENTERPRISE_TOKEN.
If you’d rather store the token, --with-token reads a classic personal access token from standard input:
gh auth login --with-token < mytoken.txt
3. Where the token ends up
After a login, gh stores the token in the system credential store. Headless Linux boxes often have none running, and then gh falls back to writing the token to a plain-text file. If that’s what you want, say so with --insecure-storage; if it isn’t, an environment token you inject at run time keeps it off the disk.
4. Point gh at a different browser
gh opens links with the browser named in GH_BROWSER, or failing that BROWSER. That matters on a box where something better than “nothing” can take the link: a script that prints a QR code, or a tool that sends the link to your phone. See Open a link from an SSH session on your phone.
Where it gets harder
gh is the easy one. The same box usually runs tools whose only login is a browser redirect to localhost:PORT: cloud CLIs, coding agents, MCP servers. Those hang the way gh doesn’t, and OAuth redirect to localhost on a remote server explains why and how to finish them.
The permanent fix
For gh itself you may not need Handback: the device code already does the job. Where Handback earns its place is everything else on the same box, the tools whose only sign-in is a browser redirect to localhost, and the plain links agents open. With the free Engine on the box (or Engine mode in the Handback app on a Mac), those links land on the iPhone, iPad or Mac in your hand, and a sign-in that redirects to localhost on the box has its callback tunnelled back from your device, so it finishes. gh opens its device page through GH_BROWSER or BROWSER, so the Engine hands you that link too; the code you type is still in the terminal. On an iPhone the app receives while it's on screen; links that arrive meanwhile wait on the box for 24 hours.
$7.99 / €7.99 · Mac, iPhone & iPad, one purchase
Sources
Every flag above was checked against these on 15 October 2026.