[!info] related notes

• 前置笔记:
• 相关 MOC:
• 相关资源: github、git

GitHub CLI（gh）命令速查

核心心智模型

git 和 gh 解决的是两层不同的问题：

• git：操作本地 Git 仓库、分支、提交、远程引用。
• gh：操作 GitHub 平台对象，例如 Issue、Pull Request、Actions、Release、Repository。

最常见的组合是：

本地代码与提交：git
        ↓ push
GitHub 协作对象：gh issue / gh pr / gh run / gh release

官方手册：https://cli.github.com/manual/

认证与环境

命令	作用
gh auth login	交互式登录 GitHub
gh auth status	查看当前认证状态
gh auth setup-git	让 Git 使用 gh 管理的 GitHub 凭据
gh auth switch	多账号之间切换
gh auth logout	退出登录
gh --version	查看 gh 版本

常见首次配置：

gh auth login
gh auth status
gh auth setup-git

[!tip] 大多数仓库相关命令都支持 -R OWNER/REPO，因此不进入仓库目录也能操作指定 GitHub 仓库。

仓库 Repo

命令	作用
gh repo clone OWNER/REPO	克隆仓库
gh repo create	创建仓库
gh repo view	查看当前仓库信息
gh repo view --web	在浏览器打开仓库
gh repo fork OWNER/REPO	Fork 仓库
gh repo sync	同步 fork 与上游
gh repo list OWNER	查看某用户或组织的仓库

常用：

gh repo view --web
gh repo clone owner/repo
gh repo list owner

Issue

查看

gh issue list
gh issue status
gh issue view 123
gh issue view 123 --web

创建

交互式：

gh issue create

直接创建：

gh issue create \
  --title "fix: onboarding observation provenance is unclear" \
  --body "Describe the problem, expected behavior, and acceptance criteria." \
  --label bug

从文件读取正文：

gh issue create --title "Issue title" --body-file issue.md

更新与关闭

gh issue comment 123 --body "补充复现信息"
gh issue edit 123 --add-label bug
gh issue close 123
gh issue reopen 123

Pull Request

创建 PR

最常用：

gh pr create --fill

指定 base：

gh pr create --base main --fill

指定标题和正文：

gh pr create \
  --base main \
  --title "fix: clarify observation provenance" \
  --body-file pr.md

草稿 PR：

gh pr create --draft --fill

查看 PR

gh pr status
gh pr list
gh pr view
gh pr view 123
gh pr view 123 --web
gh pr diff 123

Checkout 别人的 PR

gh pr checkout 123

CI / Checks

gh pr checks 123
gh pr checks 123 --watch

Review

gh pr review 123 --approve
gh pr review 123 --request-changes --body "这里还需要补测试"
gh pr comment 123 --body "我补充了一轮验证结果"

同步与合并

gh pr update-branch 123
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --merge --delete-branch
gh pr merge 123 --rebase --delete-branch

[!warning] merge / squash / rebase 应遵守仓库既有合并策略和分支保护规则，不要因为命令方便就绕过团队约定。

GitHub Actions

Workflow

gh workflow list
gh workflow view ci.yml
gh workflow run ci.yml
gh workflow run ci.yml --ref main

带输入参数：

gh workflow run deploy.yml \
  --ref main \
  -f environment=staging

gh workflow run 要求 workflow 支持 workflow_dispatch。

Run

gh run list
gh run view <run-id>
gh run watch <run-id>
gh run rerun <run-id>
gh run cancel <run-id>

只看失败日志：

gh run view <run-id> --log-failed

下载 Actions artifact：

gh run download <run-id>

一个很实用的排障顺序：

gh run list --limit 10
gh run view <run-id> --log-failed
gh pr checks <pr-number>

Release

gh release list
gh release view v1.2.0
gh release create v1.2.0 --generate-notes
gh release upload v1.2.0 ./dist/app.zip
gh release download v1.2.0
gh release edit v1.2.0

常见发版：

git tag -a v1.2.0 -m "release: v1.2.0"
git push origin v1.2.0
gh release create v1.2.0 --generate-notes

如果项目由 tag push 自动触发 Release workflow，则只执行仓库定义的正式发版流程，不要再手工重复创建 Release。

搜索与跨仓库查询

gh search repos "bodysense"
gh search issues "is:open label:bug"
gh search prs "is:open review-requested:@me"

指定仓库：

gh issue list -R owner/repo
gh pr list -R owner/repo
gh run list -R owner/repo

API 与脚本化

当内置子命令覆盖不了需求时，可以直接调用 GitHub API：

gh api repos/OWNER/REPO
gh api repos/OWNER/REPO/pulls/123

机器可读输出优先使用 --json：

gh pr list --json number,title,headRefName,state
gh run list --json databaseId,status,conclusion,headBranch

配合 --jq：

gh pr list --json number,title --jq '.[] | "#\(.number) \(.title)"'

这比解析终端表格输出更适合脚本和 Agent。

高频完整流程：Issue → Branch → Commit → PR → Merge

# 1. 创建 Issue
gh issue create --title "fix: ..." --body-file issue.md

# 2. 创建本地分支
git switch -c fix/issue-123

# 3. 修改后提交
git status
git add -p
git commit -m "fix(scope): ..."

# 4. 推送并建立 upstream
git push -u origin HEAD

# 5. 创建 PR
gh pr create --base main --fill

# 6. 检查 CI
gh pr checks --watch

# 7. 查看最终 diff
gh pr diff

# 8. 按仓库策略合并
gh pr merge --squash --delete-branch

高频命令最小集合

如果只记十几个命令，优先记这些：

gh auth status

gh repo view --web

gh issue list
gh issue create
gh issue view 123

gh pr status
gh pr create --fill
gh pr view --web
gh pr diff
gh pr checks --watch
gh pr merge --squash --delete-branch

gh run list
gh run view <run-id> --log-failed

gh workflow run <workflow>

gh release create <tag> --generate-notes

安全边界

• 删除仓库、Release、Issue 等破坏性操作前先确认目标仓库和对象编号。
• 合并 PR 前看 gh pr diff 和 gh pr checks，不要只看“能 merge”。
• 自动化脚本优先传 -R OWNER/REPO，降低在错误目录中操作错仓库的风险。
• Token 不写进命令历史或知识库；自动化环境使用安全的 Secret / 环境变量注入。

相关笔记

• GitHub
• Git
• Git 命令速查
• Git MOC
• GitHub Actions
• GitHub Actions 手动触发 workflow
• Git 分支保护