GitHub CLI

Use gh for authenticated GitHub input and output. This connector owns account selection and request mechanics; the task skills below own planning, delivery, and repository policy.

Workflow

1. Resolve the intended host and repository: from the request and Git remotes, using gh repo view --json nameWithOwner; never print raw remote URLs, which can contain credentials. Pass -R <owner>/<repo> to repository commands and --hostname <host> to API calls when needed; do not silently use an unrelated current checkout.
2. Check authentication: run gh auth status --active --hostname <host> when authentication is uncertain. Environment credentials can override stored accounts; never print token values or use --show-token. Account changes and additional OAuth scopes need authority; dot-cli authentication owns the login policy and its one-off grants.
3. Prefer bounded native commands: prefer the native command with an explicit --limit and selected --json fields. Read a remote file or directory with gh repo read-file <path> -R <owner>/<repo> --ref <sha> or gh repo read-dir (preview; pass "", not ., for the root) instead of cloning or decoding the contents API. For missing capabilities, use gh api --method GET <endpoint> with bounded per_page and page fields. Adding --field or --raw-field otherwise changes the default method to POST.
4. Read failed Actions logs first: gh run view <run-id> -R <owner>/<repo> --job <job-id> --log-failed, saved to a file when large.
5. Write from files, then read back: use --body-file or gh api --input <file> for an authorized write, re-read the changed fields, and reconcile remote state before retrying an uncertain write.

Task owners

• github-issues: issue planning, drafts, dependencies, updates, and closure.
• github-pull-request: PR creation, updates, base/head selection, verification, and merging.
• github-repository: repository metadata, visibility, and settings.
• github-actions: workflow authoring and CI/CD policy.
• git-delivery: authorized commits, pushes, and releases.

Gotchas

• Inspect auth state, not exit codes: gh auth status --json can exit zero despite authentication failures; inspect the reported state.
• Paginate only bounded collections: gh api --paginate fetches every page; use it only for a bounded, intentionally complete collection. --slurp combines page objects, not individual records.

Official Skills

Upstream cli/cli publishes agent skills, including a same-name gh: preview it, never install it under that name (vendor-skill policy). Review and install others only through the pinned official-skills procedure.

Documentation

• GitHub CLI manual · API command
• Releases: GitHub CLI