carapace-sh/carapace-bin / skills/gh
gh
FlaggedUse when working with the GitHub CLI (`gh`) — authentication, repositories, pull requests, issues, releases, GitHub Actions (workflows, runs, caches), the gh API command, extensions, secrets and variables, search, gists, SSH/GPG keys, labels, rulesets, codespaces, browsing, configuration, aliases, JSON output formatting, and environment variables. Triggers on: "gh", "gh auth", "gh repo", "gh pr", "gh issue", "gh release", "gh run", "gh workflow", "gh api", "gh extension", "gh secret", "gh variable", "gh search", "gh gist", "gh label", "gh codespace", "gh browse", "gh status", "gh config", "gh alias", "gh completion", "gh ssh-key", "gh gpg-key", "gh ruleset", "gh cache", "gh org", "GH_TOKEN", "GH_REPO", "GH_HOST", "gh pr create", "gh pr checkout", "gh pr merge", "gh repo clone", "gh repo create", "gh issue create", "gh release create", "gh workflow run", "gh run list", "gh api graphql", "gh extension install", "gh secret set", "gh search repos".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.8 KB |
| references/actions.md | markdown | 10.1 KB |
| references/api.md | markdown | 6.5 KB |
| references/auth.md | markdown | 7.4 KB |
| references/browse-status.md | markdown | 5.6 KB |
| references/config.md | markdown | 8.3 KB |
| references/extension.md | markdown | 5.4 KB |
| references/gist-keys.md | markdown | 9.3 KB |
| references/issue.md | markdown | 9.9 KB |
| references/output-formatting.md | markdown | 5.2 KB |
| references/pr.md | markdown | 14.2 KB |
| references/release.md | markdown | 8.3 KB |
| references/repo.md | markdown | 10.3 KB |
| references/search.md | markdown | 10.7 KB |
| references/secret-variable.md | markdown | 7.0 KB |
references/auth.md
View on GitHub# Authentication
How `gh` authenticates with GitHub hosts, manages credentials, and handles multi-account setups.
## Overview
`gh auth` manages authentication for GitHub.com and GitHub Enterprise Server (GHES) hosts. Credentials are stored in the system credential store (with a plain-text fallback), or supplied via environment variables. The `gh auth` command group handles login, logout, token retrieval, scope management, and git credential helper setup.
## Authentication Methods
### Web-Based Browser Flow (default)
The default `gh auth login` flow opens a browser for OAuth authentication. After completion, a token is stored securely in the system credential store. If no credential store is found, the token is written to a plain-text file (see `gh auth status` for its location).
```sh
$ gh auth login # interactive, web flow
$ gh auth login --web --clipboard # open browser, copy OAuth code to clipboard
$ gh auth login --hostname enterprise.internal
```
### Token via Standard Input
Pass a personal access token (classic) via stdin. Minimum required scopes: `repo`, `read:org`, and `gist`.
```sh
$ gh auth login --with-token < mytoken.txt
$ echo "$TOKEN" | gh auth login --with-token
```
> **Caution with fine-grained PATs**: The inherent scoping to certain resources may cause confusing behaviour when interacting with other resources. Favour setting `GH_TOKEN` for fine-grained PAT usage.
### Environment Variables (headless / automation)
gh uses authentication tokens found in environment variables. This is most suitable for "headless" use such as in automation.
| Variable | Scope |
|----------|-------|
| `GH_TOKEN` | `github.com` and subdomains of `ghe.com` (highest precedence) |
| `GITHUB_TOKEN` | `github.com` and subdomains of `ghe.com` (second precedence) |
| `GH_ENTERPRISE_TOKEN` | GitHub Enterprise Server hosts (highest precedence) |
| `GITHUB_ENTERPRISE_TOKEN` | GitHub Enterprise Server hosts (second precedence) |
For GitHub Actions, add `GH_TOKEN: ${{ github.token }}` to `env`.
## Commands
### `gh auth login`
Authenticate with a GitHub host.
| Flag | Description |
|------|-------------|
| `-c, --clipboard` | Copy one-time OAuth device code to clipboard |
| `-p, --git-protocol string` | Protocol for git operations: `ssh` or `https` |
| `-h, --hostname string` | GitHub instance hostname (default: `github.com`) |
| `--insecure-storage` | Save credentials in plain text instead of credential store |
| `-s, --scopes strings` | Additional authentication scopes to request |
| `--skip-ssh-key` | Skip generate/upload SSH key prompt |
| `-w, --web` | Open a browser to authenticate |
| `--with-token` | Read token from standard input |
When `--git-protocol ssh` is specified, gh detects existing SSH keys and prompts to create/upload a new key if none is found. Use `--skip-ssh-key` to skip this.
The `--git-protocol` setting takes effect for **all users** on the host (not just the current account), since login is per-account but the git protocol is per-host.
### `gh auth status`
Display active account and authentication state on each known GitHub host. For each host, each known account's authentication is tested and any issues are included.
| Flag | Description |
|------|-------------|
| `-a, --active` | Display the active account only |
| `-h, --hostname string` | Check only a specific hostname |
| `-t, --show-token` | Display the auth token |
| `--json fields` | Output JSON (field: `hosts`) |
| `--jq expression` | Filter JSON output |
| `--template string` | Format JSON output using a Go template |
If any account has authentication issues, the command exits with 1 and outputs to stderr. With `--json`, the command always exits 0 regardless of auth issues (unless a fatal error occurs).
### `gh auth token`
Print the authentication token for an account on a given host. Without `--hostname`, the default host is chosen. Without `--user`, the active account is chosen.
| Flag | Description |
|------|-------------|
| `-h, --hostname string` | GitHub hostname |
| `-u, --user string` | Account to output the token for |
### `gh auth switch`
Switch the active account for a GitHub host. If the host has exactly two accounts, the switch is automatic. With more than two, disambiguation is needed via `--user` or interactive prompt.
| Flag | Description |
|------|-------------|
| `-h, --hostname string` | GitHub hostname |
| `-u, --user string` | Account to switch to |
### `gh auth logout`
Remove authentication for a GitHub account. This only removes the **local** configuration — it does **not** revoke tokens. To revoke all gh-generated tokens, visit <https://github.com/settings/applications>, select "GitHub CLI", and "Revoke Access".
| Flag | Description |
|------|-------------|
| `-h, --hostname string` | GitHub hostname |
| `-u, --user string` | Account to log out of |
### `gh auth refresh`
Expand or fix permission scopes for stored credentials for the active account.
| Flag | Description |
|------|-------------|
| `-c, --clipboard` | Copy one-time OAuth device code to clipboard |
| `-h, --hostname string` | GitHub host |
| `--insecure-storage` | Save credentials in plain text |
| `-r, --remove-scopes strings` | Scopes to remove (idempotent; minimum scopes `repo`, `read:org`, `gist` cannot be removed) |
| `--reset-scopes` | Reset to the default minimum set of scopes |
| `-s, --scopes strings` | Additional scopes to add |
To refresh credentials for an **inactive** account, first `gh auth switch` to it, refresh, then switch back.
### `gh auth setup-git`
Configure `git` to use gh as a credential helper. By default, configures all authenticated hosts. Use `--hostname` for a single host.
| Flag | Description |
|------|-------------|
| `-f, --force` | Force setup even if the host is not known (requires `--hostname`) |
| `-h, --hostname string` | Hostname to configure git for |
## OAuth Scopes
The minimum required scopes for gh are: `repo`, `read:org`, and `gist`. Additional scopes can be requested at login or via `gh auth refresh`. Common additional scopes:
| Scope | Purpose |
|-------|---------|
| `project` | Adding issues/PRs to GitHub Projects |
| `write:org` | Organization write operations |
| `read:public_key` | Public key reading |
| `delete_repo` | Repository deletion |
| `admin:org` | Organization ruleset management |
For OAuth scopes documentation, see <https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/>.
## Multi-Account Support
gh supports multiple authenticated accounts per host. One account per host is "active" — it's the one used when targeting that host. Use `gh auth switch` to change the active account. `gh auth status` shows all accounts and which is active.
```
$ gh auth status
github.com
✓ Logged in to github.com as user1 (active account)
✓ Logged in to github.com as user2
enterprise.internal
✓ Logged in to enterprise.internal as corpuser (active account)
```
## Credential Storage
| Method | When Used |
|--------|-----------|
| System credential store | Default (keychain on macOS, libsecret on Linux, Credential Manager on Windows) |
| Plain-text file | Fallback when no credential store is available, or `--insecure-storage` |
| Environment variables | `GH_TOKEN`/`GITHUB_TOKEN` — takes precedence over stored credentials |
## Related
- For git credential helper internals, see the **git** skill.
- For environment variables, see [config.md](config.md).
- For making raw API requests with the token, see [api.md](api.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |