The Keychain Story

"The push succeeded. The CLI failed. Same machine, same user, same second — the only thing different was the door."

The setup

A headless SSH session on the control-plane Mac was bootstrapping a repository. Git over SSH worked perfectly: it authenticated to the remote and pushed without complaint. By every obvious measure, this session had working access to GitHub.

The wall

Then gh, the GitHub CLI, failed on the same box, in the same session, for the same user. Why? Because gh keeps its auth token in the login Keychain, and a headless SSH session has no SecuritySessionID — no login session to unlock that Keychain with. Git's SSH key lived somewhere the SSH envelope could reach; gh's token lived somewhere it couldn't. One machine, one user, two credentials in two different rooms — and this door only opened one of them.

The wrong fix

The reflex was gh auth login — re-authenticate, surely that fixes an auth failure. It doesn't. Re-authenticating inside an envelope that structurally cannot hold the credential just produces a fresh failure. You can run gh auth login a hundred times; the headless door still has no session to unlock the Keychain the new token would land in. The loop feels like progress and is pure motion.

The right fix

Use the capability you actually have. The SSH transport had already authenticated and pushed — so lean on that. Or, if the task genuinely needs the Keychain token, run it through an interactive executor that has a login session. The operation never needed a new credential; it needed the right envelope for the credential it already had. Host identity did not imply credential availability — and that gap is the whole lesson.

Reaching a machine is not holding its keys. When a credential fails in one envelope, the fix is a different envelope — not the same closed door, knocked harder.

Code

Same session, two credentials, two outcomes·bash

# Headless SSH session on the control-plane Mac. Same user, same second.

git push origin main       # OK   -- SSH key auth; reachable from this envelope
gh pr create ...           # FAIL -- token is in the login Keychain, and a
                           #         headless SSH session has no login session
                           #         (no SecuritySessionID) to unlock it

# WRONG fix -- re-auth in a door that can't hold the key:
gh auth login              # 'succeeds', then fails again the same way. forever.

# RIGHT fix -- use the envelope that works, or one with Keychain access:
#   * lean on the SSH transport that already authenticated, OR
#   * run gh through an INTERACTIVE executor with a login session.
# The credential was never missing; the envelope simply couldn't reach it.

Exercise

Recall a time you fought an 'authentication' error that turned out to be about context, not credentials (a cron job that couldn't see your env, a CI runner missing a secret, an SSH session that couldn't reach your keychain/agent). Write down the wrong fix you tried first, and the envelope-level fix that actually worked.

Hint

The wrong fix is almost always 're-do the credential.' The real fix is almost always 'run it from a door that already has the credential, or hand the credential to the door explicitly.' Naming the door first would have saved the detour.

The setup

The wall

The wrong fix

The right fix

Code

External links

Exercise

Progress

Comments 0