Gh CLI

TL;DR

• 目的：Enforces authenticated gh CLI workflows over unauthenticated curl/WebFetch patterns. Use when working with GitHub URLs, API access, pull req…
• 适用：工具/扩展辅助
• 输入：API 端点 + 鉴权方式
• 输出：GitHub PR/Issue 列表 + workflow run 状态 + 仓库元数据
• 红线：仅限授权范围内；破坏性 POC 先用只读变体；全 RCE 前明确批准
• 关联：上游：003-src-session-start → 下游：170-git-cleanup, 171-github-triage, 168-claude-in-chrome-troubleshooting

Workflow

1. Set up authentication — gh auth login or set GITHUB_TOKEN environment variable
2. Verify — gh auth status to confirm login and scopes
3. Clone or fork — gh repo clone owner/repo or gh repo fork owner/repo
4. Create branch — gh repo sync then git checkout -b feature/xxx
5. Work in branch — make changes, commit, push
6. Create PR — gh pr create --fill or with explicit flags
7. Review and merge — gh pr review, gh pr merge

Common Operations

# 查看当前 issue 列表
gh issue list --assignee @me

# 创建 issue
gh issue create --title "..." --body "..."

# 查看 PR
gh pr view 123

# 本地 checkout PR
gh pr checkout 123

# merge
gh pr merge 123 --squash --delete-branch

# 触发 workflow
gh workflow run build.yml

# 看 run 列表
gh run list --workflow=build

Why use gh CLI instead of curl + webfetch

• Authenticated by default — uses ~/.config/gh/hosts.yml credentials
• Proper User-Agent — gh/2.x.x is whitelisted by GitHub
• API version handling — automatically uses latest stable API
• Pagination — built-in --limit and --paginate
• Scope control — explicit --scopes flag
• Less fingerprinting — uniform tool signature vs. custom scripts

gh-cli

When to Use

• Working with GitHub repositories, pull requests, issues, releases, or raw file URLs.
• You need authenticated access to private repositories or higher API rate limits.
• You are about to use curl, wget, or unauthenticated web fetches against GitHub.

When NOT to Use

• The target is not GitHub.
• Plain local git operations already solve the task.

Guidance

Prefer the authenticated gh CLI over raw HTTP fetches for GitHub content. In particular:

• Prefer gh repo view, gh pr view, gh pr list, gh issue view, and gh api over unauthenticated curl or wget.
• Prefer cloning a repository and reading files locally over fetching raw.githubusercontent.com blobs directly.
• Avoid using GitHub API /contents/ endpoints as a substitute for cloning and reading repository files.

Examples:

gh repo view owner/repo
gh pr view 123 --repo owner/repo
gh api repos/owner/repo/pulls

For the hook implementation, see:

• plugins/gh-cli/README.md
• plugins/gh-cli/hooks/

Advanced Techniques

Branch Management

# 列出所有远程分支
gh api repos/{owner}/{repo}/branches --jq '.[].name'

# 清理已合并的远程分支
gh api -X DELETE repos/{owner}/{repo}/git/refs/heads/<branch>

Workflow Automation

# 创建 workflow dispatch
gh workflow run build.yml --ref main -f environment=staging

# 查看 workflow runs
gh run list --workflow=build --limit 20
gh run watch 12345

Security Auditing with gh

# 检查代码库是否有 secrets
gh secret list

# 查看 repo 安全告警
gh api repos/{owner}/{repo}/secret-scanning/alerts