GitHub CLI Auth Troubleshooting

Problem Context

Last Friday at 4 PM, I was adding CI/CD functionality to a VPS deployment script. I needed to push build artifacts directly to a private repo from the server. I wrote .github/workflows/deploy.yml, tested gh auth status locally — logged in. Synced the script to the VPS and ran it:

$ gh auth status
✓ GitHub CLI is authenticated

But when I ran gh workflow run build, I got:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

SSH key was added, token showed valid, push failed. What was going on?

---

Debugging Process

Step 1: Confirm gh's Own Authentication State

gh auth status --hostname github.com

Look for: git credential configuration and auth type used during gh auth login (browser/token/SSH key). The output will show whether gh is using token-based auth and which git protocol is configured.

Step 2: Check git credential helper

gh CLI uses git credential helper to store and pass auth info. Check current config:

git config --global credential.helper
# Output: store

Common issue: credential helper points to the wrong storage (old, nonexistent file).

Fix:

gh auth git-credential
# Outputs the current git credential helper command gh uses
# If empty, gh can't pass auth info correctly

In my actual debugging, I found that the ~/.git-credentials file on the VPS had wrong permissions (600), preventing git from reading it. Fix:

chmod 600 ~/.git-credentials

Step 3: Check GITHUB_TOKEN Environment Variable

If you use gh in GitHub Actions, Actions automatically sets GITHUB_TOKEN. But if you're on a local VPS using your own token:

echo $GITHUB_TOKEN
# If empty, shell doesn't have the token
gh auth status
# Shows: Authentication failures. Run: gh auth login

**Key point**: Sometimes gh auth login uses interactive browser login — if your VPS is headless (no browser), the login hangs. I encountered this exact issue on an Alibaba Cloud ECS instance running Ubuntu 22.04. The cursor just stuck at Authentication pending with no way to complete it.

Solution: login with token instead of browser:

gh auth login --with-token < your-token-file

This bypasses the browser entirely and directly imports the token.

Step 4: SSH Key vs Token Authentication

gh supports two auth methods:

• **Token auth**: Via `GITHUB_TOKEN` env var or `~/.config/gh/hosts.yml`
• **SSH key auth**: Via git's SSH URL

If the repo uses git@github.com:owner/repo.git format, git goes SSH. If using https://github.com/owner/repo.git, git goes HTTPS (needs token).

Check remote URL:

git remote -v
# If shows git@github.com → SSH
# If shows https://github.com → HTTPS

The output typically shows both fetch and push URLs. Both should use the same protocol.

Step 5: Check hosts.yml Configuration

gh's auth info lives in ~/.config/gh/hosts.yml (Linux/Mac) or %APP_DATA%\GitHub CLI\hosts.yml (Windows).

cat ~/.config/gh/hosts.yml

Correct format:

github.com:
  oauth_token: gho_xxxxxxxxxxxx
  user: your-username
  git_protocol: https  # or ssh

Common issue: git_protocol: ssh but SSH agent isn't running. If you set git_protocol: ssh, gh assumes your git operations will go through SSH, which requires ssh-agent to be running and your key loaded.

Check SSH agent:

ssh-add -l
# If shows "The agent has no identities.", no keys are loaded
# If shows a key fingerprint, SSH agent is working

Step 6: Verify the Actual Git Operation

The most diagnostic step — directly test git with verbose output:

GIT_SSH_COMMAND="ssh -v" git push origin main
# This shows exactly which SSH key git is trying to use
# and where the connection fails

Or for HTTPS:

GIT_CURL_VERBOSE=1 git push origin main
# Shows full HTTP handshake and auth headers

---

The Real Cause

My issue: After importing token via gh auth login --with-token on the VPS, gh configured git_protocol: https, but the git remote URL was still SSH format (git@github.com:...).

My Mac's gh was configured git_protocol: ssh — worked fine locally. The VPS was a fresh Ubuntu 24.04 install where gh defaulted to HTTPS on that machine. The mismatch meant gh thought it could use token auth, but git was trying to use SSH — and since no SSH key was loaded on the VPS, the push failed.

Fix:

gh auth setup-git
# Configures git credential helper based on current gh auth configuration

Then either:

git remote set-url origin https://github.com/owner/repo.git
# Switch to HTTPS

Or:

git remote set-url origin git@github.com:owner/repo.git
# Keep SSH, but then you need SSH key configured

---

Prevention Methods

1. **Don't assume local and remote configs match**. Before running CI on a new environment, verify both gh auth status and git remote -v — I now make this a checklist item in every deployment runbook

2. Prefer HTTPS URLs for automation. GitHub deprecated SSH password authentication in 2021 (source: GitHub Blog, August 2021), and HTTPS token is more reliable for scripted operations — no SSH agent dependency

3. **Use gh auth setup-git** after any gh auth login. This single command auto-configures git credential helper correctly — don't do it manually, you'll get it wrong

4. Add auth checks to deployment scripts. Check auth status before deploying to catch failures early:

gh auth status || { echo "GitHub not authenticated. Run: gh auth login"; exit 1; }
git remote -v | grep -q "https://github.com" || echo "Warning: not using HTTPS"

5. Document the auth setup steps in your README. When you set up a new server, you shouldn't have to rediscover this.

---

When This Applies

• CI/CD scripts running on VPS/cloud servers (Alibaba Cloud, AWS EC2, DigitalOcean Droplets)
• Custom Actions in GitHub workflows that need gh CLI
• Managing GitHub resources across multiple machines or environments
• Deploying from containers where git and gh both need consistent auth

Doesn't apply:

• GitHub Desktop (doesn't go through gh CLI)
• Desktop environments where you can access github.com via browser interactively

---

Affiliate link disclosure: This article contains affiliate links. MiniMax API is a tool I've been using for 6 months in my content automation workflows. Purchasing through the link above earns me a commission at no extra cost to you.

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

👉 Try MiniMax API now: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link