---
name: github-cli
which: gh
disable-model-invocation: true
description: "Access GitHub issues, pull requests, releases, comments, Actions, and repository metadata through the gh CLI. Use when local VCS data is insufficient."
---

# GitHub CLI

Use `gh` for GitHub API and UI state that local version-control commands cannot reach.

## Source of truth

Command shapes change.
Check `gh --version`, authentication status, and the relevant installed help before acting.
Use the official manual at <https://cli.github.com/manual/> when installed help is insufficient.

## Safety

Default to read-only operations such as list, view, status, search, and logs.
A mutation requires an explicit request covering that mutation, including:

- issue or pull-request creation, editing, closing, reopening, comments, labels, or assignment;
- review submission, approval, requested changes, merge, checkout, or draft-state changes;
- release creation, deletion, or upload;
- workflow rerun, cancellation, or dispatch;
- GitHub Pages changes;
- non-GET `gh api` requests.

`ok` acknowledges a report or plan; it does not authorize execution.
Review publication requires approval of the exact PR, head commit, event, body, and inline comments, followed by read-back verification.
PR merge requests require current review, approval, protection, and check outcomes before execution.
Never print tokens, generate destructive bulk API pipelines, or bypass protections unless the repository permits it and the user explicitly authorizes that exact operation.

## Local helpers

Resolve these paths relative to this skill directory:

- [Code search](references/code-search.md): `node scripts/gh_code_search.mjs "query" --language javascript --exclude-forks`
- [Failed Actions run](references/failed-run.md): `node scripts/gh_failed_run.mjs --repo owner/repo --pretty`
- [Pages deployment](references/pages-deploy.md): `node scripts/gh_pages_deploy.mjs status owner/repo --json`

Helpers use Node `.mjs`; run `npm test` for their tests.

## Patterns

```bash
gh issue list --repo owner/repo --state open --limit 20
gh issue view 123 --repo owner/repo --json comments
gh pr view 456 --repo owner/repo --json commits,reviews,statusCheckRollup
gh run view --repo owner/repo --log-failed
gh release list --repo owner/repo --limit 10
gh search code "TODO" --owner org --limit 50
```

For JSON processing, prefer `gh --jq`, `gh --template`, or the reviewed Node helpers.