GitHub CLI Authentication

This page is the operator surface for GitHub CLI (gh) auth forwarding. For the broader pattern jackin’ applies across every auth axis, see the Authentication overview.

gh auth follows the same three-mode shape as agent auth (sync / token / ignore) at the same three scopes (global default, per-workspace, per-(workspace × role)). One difference: gh forwarding has no agent dimension — the same gh login is shared by every agent in the container, because gh itself doesn’t care which runtime is calling it.

What you get out of the box

If you’re already logged in to gh on your host (gh auth login once on the host), you don’t need to do anything else. On every jackin load and every jackin console launch:

Your host’s gh login is forwarded into the freshly started container. The agent inside sees gh auth status as logged in to github.com.
The container is wired so git push over HTTPS authenticates automatically using that login — even when the host repo’s origin URL is SSH (git@github.com:owner/repo). The container rewrites the URL to HTTPS internally; your host repo’s remote URL is not modified.
The launch summary prints a one-line notice telling you which gh mode is active and where the forwarded token came from.

Modes

Three modes, mirroring the shape of agent auth, configurable at three scopes (global default, per-workspace, per-(workspace × role)):

sync (default) — forward your host’s gh login into the container on each launch. When you’re logged out on the host, any login that already exists inside the container (from a previous run) is preserved instead of getting wiped.
token — authenticate inside the container using a scoped token (typically a fine-grained PAT scoped to one repo or org) supplied through the operator env-vars layer. Useful when a workspace or specific role should use a different GitHub identity than your broad host login.
ignore — gh starts unauthenticated inside the container. Agents that need gh must run gh auth login themselves.

For GitHub Enterprise hosts, set GH_HOST (and optionally GH_ENTERPRISE_TOKEN) at the workspace’s env-vars scope; both flow through to the container unchanged.

Setting non-default modes

sync is the default. You only need to do anything here if you want token or ignore for a specific workspace or role. Manage gh modes through the same surface as agent auth: jackin console → select the workspace → Auth tab — see the overview for the management story shared across every auth axis.

The dedicated GitHub CLI row in the console’s Auth tab is wired for workspace and per-role modes. A dedicated jackin config auth set --target github CLI subcommand is still planned; use the console for non-default workspace and role settings.

Launch-time messaging

Every container launch prints a one-line gh auth: notice that tells you which mode is active and where the forwarded token came from. Sample output:

gh auth: forwarded host token (sync, via gh CLI)
gh auth: forwarded host token (sync, via ~/.config/gh/hosts.yml)
gh auth: scoped token from Work/ACME/github-fine-grained-pat (token)
gh auth: none — host has no gh login, container preserves prior login
gh auth: none — gh auth token failed: …; container preserves prior login
gh auth: disabled (ignore)

The sync notice distinguishes whether the token came from the live gh CLI on your host (current — picks up Keychain on macOS) or from a parse of your host’s gh config file (file-based fallback, potentially stale). Either path shipping the same token is normal; the attribution exists so you can audit drift between intended and actual auth source at a glance.

When the host is logged out or the host’s gh is in a broken state (expired token, revoked grant, missing binary), the notice describes the actual reason instead of a generic “host logged out” — including failure stderr from gh auth token when that’s what produced the missing token. That makes it easy to tell “my host gh is fine, I just don’t have a login” apart from “my host gh is silently broken and I should fix it before trusting the container’s auth”.

Host machine is never modified

gh auth forwarding follows jackin’s repo-wide never mutate the host rule. The SSH→HTTPS git rewrite, the gh credential helper, and forwarded hosts.yml all live inside the container or in jackin’s own state directory — your ~/.gitconfig, your host repo’s .git/config, and your ~/.config/gh/ are read but never written.