name: github-cli
description: Safety-first GitHub CLI skill wrapping gh (v2.86+). Use when performing GitHub operations — PRs, issues, releases, repos, Actions, API calls. Enforces risk classification with mandatory confirmation for destructive/forbidden operations.
author: George Khananaev
GitHub CLI
Safety-first wrapper for GitHub CLI (gh). Every command is classified by risk level before execution.
When to Use
- User asks to create, list, merge, or close PRs
- User asks to manage issues, releases, or repos
- User asks to check CI/CD status or workflow runs
- User asks to call the GitHub API via
gh api
- User asks to manage GitHub Actions secrets or variables
Prerequisites
- Install:
brew install gh or see https://cli.github.com
- Auth:
gh auth login
- Verify:
gh --version (requires v2.86+)
- Scopes:
gh auth status — confirm repo, read:org scopes minimum
Safety Model
Every gh command falls into one of four risk tiers:
| Tier | Action Required | Examples |
|---|
| Safe | Execute immediately | gh pr list, gh issue view, gh repo view |
| Write | Inform user, then execute | gh pr create, gh issue create, gh release create |
| Destructive | AskUserQuestion BEFORE executing | gh pr merge, gh pr close, gh release delete |
| Forbidden | Multi-step validation, NEVER auto-confirm | gh repo delete, gh repo transfer, visibility changes |
See references/safety-rules.md for the full classification and confirmation templates.
Decision Flow
Command received
→ Classify risk tier (see Quick Reference)
→ Safe? Execute immediately
→ Write? Inform user what will happen → execute
→ Destructive? AskUserQuestion with options → wait for answer → execute or cancel
→ Forbidden? Warn → require typed confirmation → final confirm → execute or cancel
Quick Reference
Safe (read-only, execute immediately)
| Command | Description |
|---|
gh pr list | List pull requests |
gh pr view | View PR details |
gh pr checks | View CI status |
gh pr diff | View PR diff |
gh issue list | List issues |
gh issue view | View issue details |
gh repo view | View repo info |
gh repo list | List repos |
gh repo clone | Clone a repo |
gh release list | List releases |
gh release view | View release details |
gh run list | List workflow runs |
gh run view | View run details |
gh run view --log | View run logs |
gh workflow list | List workflows |
gh workflow view | View workflow details |
gh run download | Download workflow artifacts |
gh api (GET) | Read-only API calls |
gh auth status | Check auth |
gh browse | Open repo in browser |
gh status | Check your GitHub dashboard |
gh gist list | List your gists |
gh gist view | View gist details |
gh label list | List labels |
gh search repos | Search repos |
gh search issues | Search issues |
gh search prs | Search PRs |
gh search code | Search code |
Write (inform, then execute)
| Command | Description |
|---|
gh pr create | Create PR |
gh pr edit | Edit PR metadata |
gh pr comment | Comment on PR |
gh pr review | Submit review |
gh pr ready | Mark PR as ready |
gh pr checkout | Check out a PR branch locally |
gh issue create | Create issue |
gh issue edit | Edit issue |
gh issue comment | Comment on issue |
gh issue reopen | Reopen a closed issue |
gh issue pin | Pin an issue |
gh issue unpin | Unpin an issue |
gh label create | Create label |
gh label edit | Edit label |
gh release create | Create release |
gh repo create | Create new repo |
gh repo edit | Edit repo settings (non-visibility) |
gh repo fork | Fork a repo |
gh repo rename | Rename a repository |
gh gist create | Create a new gist |
gh gist edit | Edit an existing gist |
gh run rerun | Re-run workflow |
gh workflow enable | Enable workflow |
gh workflow disable | Disable workflow |
gh workflow run | Manually trigger a workflow |
gh secret set | Set secret |
gh variable set | Set variable |
gh api -X POST/PUT/PATCH | Write API calls |
Destructive (AskUserQuestion required)
| Command | Description |
|---|
gh pr merge | Merge PR (irreversible in most workflows) |
gh pr close | Close PR |
gh issue close | Close issue |
gh issue delete | Delete issue (permanent) |
gh issue transfer | Transfer issue to another repo |
gh release delete | Delete release |
gh label delete | Delete label |
gh repo archive | Archive repo |
gh secret delete | Delete secret |
gh variable delete | Delete variable |
gh auth logout | Log out of GitHub CLI |
gh run cancel | Cancel running workflow |
gh api -X DELETE | Delete API calls |
Forbidden (multi-step validation)
| Command | Description |
|---|
gh repo delete | Delete repository (PERMANENT) |
gh repo transfer | Transfer repo ownership |
gh repo edit --visibility | Change repo visibility |
| Bulk destructive loops | Any loop running delete/close/merge |
Workflow Patterns
Pull Requests
# List open PRs
gh pr list
# Create PR (Write — inform user first)
gh pr create --title "feat: add auth" --body "$(cat <<'EOF'
## Summary
- Add JWT authentication middleware
## Test plan
- [ ] Unit tests pass
- [ ] Manual login flow verified
EOF
)"
# View PR with checks
gh pr view 42
gh pr checks 42
# Merge PR (Destructive — AskUserQuestion first)
gh pr merge 42 --squash --delete-branch
Issues
# List issues with filters
gh issue list --label bug --assignee @me
gh issue list --state closed --limit 10
# Create issue (Write)
gh issue create --title "Bug: login fails" --body "Steps to reproduce..." --label bug
# View issue
gh issue view 123
# Close issue (Destructive — confirm first)
gh issue close 123 --reason completed
Releases
# List releases
gh release list
# Create release (Write — inform user)
gh release create v1.2.0 --generate-notes --title "v1.2.0"
# Create release with assets
gh release create v1.2.0 ./dist/*.tar.gz --title "v1.2.0" --notes "Release notes here"
# Delete release (Destructive — confirm first)
gh release delete v1.2.0
CI/CD & Actions
# List recent runs
gh run list --limit 10
# View specific run
gh run view 12345
# View logs for failed run
gh run view 12345 --log-failed
# Re-run failed jobs (Write)
gh run rerun 12345 --failed
# Cancel running workflow (Destructive — confirm)
gh run cancel 12345
# Manage secrets (Write for set, Destructive for delete)
gh secret set API_KEY --body "sk-..."
gh secret list
Repository
# View repo info
gh repo view
# Create repo (Write)
gh repo create my-app --public --clone
# Clone
gh repo clone owner/repo
# Fork (Write)
gh repo fork owner/repo --clone
# Archive (Destructive — confirm first)
gh repo archive owner/repo
API
# GET (Safe)
gh api repos/owner/repo/pulls
gh api repos/owner/repo/issues/123/comments
# POST (Write)
gh api repos/owner/repo/issues -f title="Bug" -f body="Description"
# DELETE (Destructive — confirm first)
gh api repos/owner/repo/issues/123/labels/bug -X DELETE
AskUserQuestion Integration
For Destructive operations, use AskUserQuestion with tailored options:
PR Merge Example
Question: "How should PR #42 'feat: add auth' be merged?"
Options:
- "Squash and merge" — Combine all commits into one
- "Create merge commit" — Preserve commit history
- "Rebase and merge" — Rebase onto base branch
- "Cancel" — Do not merge
PR/Issue Close Example
Question: "Close PR #42 'feat: add auth'?"
Options:
- "Close only" — Close without deleting branch
- "Close and delete branch" — Close PR and remove source branch
- "Cancel" — Keep open
Delete Example
Question: "Delete release v1.2.0?"
Options:
- "Delete release only" — Keep the git tag
- "Delete release and tag" — Remove both release and git tag
- "Cancel" — Keep release
For Forbidden operations, follow the triple-confirmation protocol in references/safety-rules.md.
Error Handling
| Error | Cause | Fix |
|---|
gh: command not found | Not installed | brew install gh |
authentication required | Not logged in | gh auth login |
HTTP 403 | Insufficient scopes | gh auth refresh -s scope |
HTTP 404 | Repo not found or no access | Check repo name and permissions |
HTTP 422 | Validation failed | Check required fields, branch exists |
HTTP 409 | Merge conflict | Resolve conflicts first |
HTTP 429 | Rate limited | Wait, or use --limit to reduce calls |
GraphQL: ... | API query error | Check field names and types |
CLI Flags Reference
| Flag | Description |
|---|
--json fields | Output specific JSON fields |
--jq expr | Filter JSON with jq expressions |
--template tmpl | Format output with Go templates |
-R owner/repo | Target a different repo |
--limit N | Limit results |
--state open|closed|all | Filter by state |
--label name | Filter by label |
--assignee user | Filter by assignee |
--author user | Filter by author |
--web | Open in browser |
Shell Safety
- No interactive mode: Never use
-i or --interactive flags
- No pagers: Always pipe to
cat if output may trigger a pager: gh pr list | cat
- Timeouts: Set reasonable timeouts for commands that could hang
- Quote arguments: Always quote multi-word arguments and heredoc bodies
- Never pass
--yes to forbidden operations — always require explicit confirmation
Integration
Pairs with:
- code-quality — Review code before PR creation
- brainstorm — Design features before opening issues
- codex-cli — Second-opinion audit before merging PRs
- gemini-cli — Alternative AI review for PR changes