# GitHub CLI Authentication (https://jackin.tailrocks.com/guides/authentication/github-cli/)



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](/guides/authentication/).

`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 [#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:

1. 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`.
2. 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**.
3. The launch summary prints a one-line notice telling you which `gh`
   mode is active and where the forwarded token came from.

## Modes [#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 [#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](/guides/authentication/#managing-auth--always-through-the-operator-console) 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 [#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:

```text
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 [#host-machine-is-never-modified]

`gh` auth forwarding follows jackin❯ repo-wide
[*never mutate the host*](/getting-started/design-principles/#never-mutate-the-host-machine-silently)
rule. The `SSH→HTTPS` git rewrite, the `gh` credential helper, and
forwarded `hosts.yml` all live inside the container or in jackin❯
own state directory — your `~/.gitconfig`, your host repo's
`.git/config`, and your `~/.config/gh/` are read but never written.
The container-level git rewrite and credential-helper setup run once
per running container; new tabs and split panes reuse that prepared
container state while still receiving their own agent environment.

## See also [#see-also]

* [Authentication overview](/guides/authentication/) — the shared modes / scopes / defaults pattern jackin❯ applies across every auth axis.
* [Agent Authentication](/guides/authentication/agents/) — parallel flow for `Claude Code`, `Codex`, `Amp`, `Kimi`, `OpenCode`, and `Grok` agent auth.
* [Environment Variables](/guides/environment-variables/) — how the operator env-vars model supplies `GH_TOKEN` for the `token` mode.