GitHub Adapter (ga)

GitHub Adapter lets clients that expect GitHub CLI semantics operate repositories hosted by different Git providers. Codex (and any gh client) keeps calling gh; ga routes each call to the Active Provider for the current repository.

• GitHub is a transparent pass-through to the real installed gh (ADR-0001).
• GitLab is served by the official ga-provider-gitlab adapter, which drives the native glab CLI (ADR-0005/0014).
• Custom Providers point at a user-declared adapter executable that implements the versioned Compatibility Contract (ADR-0003).

See CONTEXT.md for the domain language and docs/adr for the design decisions this v1 implements.

How it works

ga setup installs a gh shim into a dedicated per-user directory and asks you to prepend that directory to PATH (ADR-0010). The shim intercepts gh invocations and routes them:

gh <args>
  └─ shim → Active Provider
        ├─ github  → next real gh on PATH (outside the shim dir)
        └─ gitlab  → ga-provider-gitlab → glab

Provider selection has two layers:

• Repository Selection (ga use <provider>) is stored in the repo's local .git/config and never committed (ADR-0007).
• Global Default (ga default <provider>) is stored in per-user config and used when a repo has no selection.

Quick start

make build
bin/ga setup                     # install the gh shim
export PATH="$HOME/Library/Application Support/ga/shim:$PATH"   # macOS
bin/ga default github            # or: gitlab
cd some-repo && bin/ga use gitlab
gh pr list                       # routed to glab
bin/ga doctor                    # verify shim + PATH order + availability

Commands

Command	Purpose
ga use <provider>	Set the Repository Selection (local .git/config)
ga default [provider]	Show or set the Global Default
ga provider	Show the Active Provider and where it resolved from
ga providers	List built-in and Custom Providers with availability
ga custom add <name> <exe>	Declare a Custom Provider
ga custom remove <name>	Remove a Custom Provider
ga setup / ga uninstall	Install / remove the gh shim
ga doctor	Diagnose shim, PATH order, and provider availability
ga version	Print ga and the pinned gh contract version

Compatibility Contract

ga pins exactly one gh version per release (ADR-0004). The normative, machine-readable command surface — every command, subcommand, alias, flag, value placeholder, argument block, environment variable, and exit code — is derived directly from the real gh 2.92.0 binary (ADR-0017) and stored in contract/gh-contract.json. A Provider Adapter (official or custom) targets this manifest to reproduce gh behavior (ADR-0003). contract/contract.json is the small index that points to it.

Output conformance

The contract also pins the observable output format each command must reproduce (ADR-0006):

• Default output is line-based text.
• Every command that supports --json carries the exact, enumerated set of JSON field names gh exposes (probed from the pinned binary — e.g. gh pr list has 46 fields), plus whether --jq and --template formatting apply.
• Scenario-dependent values (ids, titles, dates, urls) are treated as typed variables/patterns, not fixed strings, so conformance stays exact on structure and format without hardcoding impossible byte-for-byte values.

An adapter therefore knows precisely which fields a --json response must contain and how clients may reshape it.

Regenerate the manifest from the pinned binary:

make contract          # needs gh 2.92.0 on PATH, or GH_BIN=/path/to/gh
make docs              # render human-readable references from the manifest

make docs produces a browsable gh command reference and the GitLab compatibility matrix from the same source of truth (ADR-0006). The GitLab adapter classifies the entire gh command surface as supported, partial, or unsupported; unsupported requests return a stable Unsupported Capability failure with exit status 3 (ADR-0002), and a test asserts every matrix entry names a real command in the contract.

The classification is exhaustive: a test asserts every one of the 202 leaf commands in the pinned contract resolves to a support level, so no command-surface entry is left unclassified (ADR-0002). Family-level defaults plus per-command overrides drive it, and the adapter can print its full matrix with ga-provider-gitlab --ga-matrix.

gh api and glab version

gh api translates only the REST endpoints in the adapter's documented allowlist; unknown REST endpoints and any GraphQL operation return Unsupported Capability rather than being forwarded as native GitLab calls (ADR-0012). The adapter also enforces a minimum glab version before running commands and reports it via ga doctor; an older glab fails explicitly (ADR-0014).

Credentials are never reinterpreted across providers: GitHub tokens are stripped before invoking the GitLab adapter, which relies on glab for auth (ADR-0013/0014).

Development

make test    # deterministic, offline (ADR-0015)
make vet
make cross   # macOS + Windows build smoke (ADR-0008)
make docs    # regenerate the compatibility matrix

Linux is outside v1 scope (ADR-0008). Live provider tests against real GitLab sandboxes are kept separate from deterministic CI (ADR-0015).

Contributing

Contributions are welcome. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community expectations. Security reports go through SECURITY.md.

License

Released under the MIT License.