gh-cli

name	gh-cli
description	Reliably drive the GitHub gh CLI for issue, PR, and label operations in automation and subagent environments, with pre-flight verification so you never fabricate a success or a fake issue URL.
user-invocable	false
disable-model-invocation	true
license	Apache-2.0
compatibility	claude-code
metadata	{"updated_at":"2026-05-29T00:00:00.000Z"}
tags	["github","gh","cli","issues","pull-requests","labels","automation","ci","troubleshooting"]
progressive_disclosure	{"entry_point":{"summary":"Reliably drive the GitHub gh CLI for issue/PR/label work, with pre-flight auth verification so you never fabricate a success.","when_to_use":"When creating, listing, editing, or closing GitHub issues/PRs/labels via gh, especially inside automation or a subagent shell.","quick_start":"1. Run gh auth status and gh repo view BEFORE any op. 2. If auth fails, STOP and report the exact error. 3. Use --json/--jq to parse and confirm results."}}

GitHub gh CLI

Reliable patterns for using the GitHub gh CLI for issue, PR, and label operations — built for automation and subagent environments where silent auth failures are common and fabricating a result is the worst outcome.

When to Use: Any time you create, list, view, edit, or close GitHub issues / PRs / labels through gh, particularly inside a sandboxed shell or a delegated subagent.

---

The One Rule: Never Fabricate

When an operation cannot be verified as succeeded, report the failure with the exact error. Never invent an issue number, a URL, or a "created successfully" message. A loud, accurate failure is always better than a fake success — downstream agents and humans act on what gets reported.

---

1. Pre-flight Verification (run BEFORE any operation)

Always confirm authentication and repo access first. These are cheap, read-only, and catch the overwhelming majority of failures before you mutate anything.

# 1. Confirm you are authenticated and see which account/scopes are active
gh auth status

# 2. Confirm you can actually reach the target repo (proves token + SSO + network)
gh repo view <org>/<repo> --json name,url

• If gh auth status reports "not logged into any GitHub hosts" or any error, STOP. Do not run create/edit/close. Diagnose using the sections below, then report the exact error verbatim.
• If gh repo view fails (404, SAML, Bad credentials), STOP. The token may be valid but lack access to this org/repo. Report the exact error.
• Only proceed to mutating operations once both commands succeed.

In a subagent: treat a failed pre-flight as a hard stop. Returning "I created issue #42" when auth failed is the failure mode this skill exists to prevent.

---

2. Gotcha: Sandbox / OS keychain access

gh's OAuth (keyring) tokens are stored in the OS keychain (macOS Keychain, Linux Secret Service). A sandboxed shell cannot read the keychain, so gh falls back to "no credentials found" and reports "not logged into any GitHub hosts" — even though valid credentials exist.

Symptom: gh auth status says not logged in, but the same command works in a normal terminal.

Fix: Run gh with the sandbox disabled so it can reach the keychain.