GitHub CLI (gh) 技能 是做什么的?
使用 gh CLI 从终端与 GitHub 仓库、议题、拉取请求和 GitHub Actions 工作流进行交互。
前提条件
验证已安装 gh 并完成身份验证:
gh --version
gh auth status
如果尚未验证身份,请运行 gh auth login 并按照提示操作。
核心工作流程
议题管理
# 列出议题
gh issue list # 当前仓库中开放的议题
gh issue list --state all # 所有议题,包括已关闭的
gh issue list --assignee @me # 分配给你的议题
gh issue list --label "bug" # 按标签筛选
# 创建议题
gh issue create -t "标题" -b "描述"
gh issue create -t "标题" --label "bug,priority:high" --milestone "milestone-1"
gh issue create # 交互模式
# 查看/更新议题
gh issue view 123 # 查看议题详情
gh issue view 123 --web # 在浏览器中打开
gh issue edit 123 --add-label "in-progress"
gh issue close 123
gh issue reopen 123
# 添加评论
gh issue comment 123 -b "正在处理”
分支与提交工作流程
# 创建功能/修复分支
git checkout -b feature/my-feature
git checkout -b fix/issue-123
git checkout -b draft/wip-experiment
# 暂存并提交更改
git add .
git commit -m "feat: 添加新功能"
git commit -m "fix: 解决 issue #123"
# 将分支推送到远程
git push -u origin feature/my-feature
拉取请求管理
# 创建 PR(多种方法)
gh pr create # 交互模式
gh pr create --fill # 从提交中自动填充
gh pr create --draft # 创建为草稿
gh pr create --draft --fill # 草稿并自动填充
gh pr create -t "标题" -b "描述" -B main
gh pr create --label "review-needed" --assignee @me
# 列出 PR
gh pr list # 开放的 PR
gh pr list --assignee @me # 你的 PR
gh pr list --search "review-requested:@me" # 请求你审查的 PR
gh pr list --draft # 仅草稿 PR
# 查看 PR 详情
gh pr view 45 # 在终端中查看 PR
gh pr view 45 --web # 在浏览器中打开
代码审查工作流程
# 本地检出 PR 进行测试
gh pr checkout 45 # 本地检出 PR 分支
# 审查更改
gh pr diff 45 # 查看 PR 差异
gh pr diff # 当前分支 PR 的差异
# 添加审查评论
gh pr comment 45 -b "LGTM,第 42 行有小的建议"
gh pr comment -b "请添加测试" # 在当前分支的 PR 上评论
# 提交正式审查
gh pr review 45 --approve
gh pr review 45 --request-changes -b "请修复错误处理"
gh pr review 45 --comment -b "总体不错,有一些建议"
# 合并
gh pr merge 45 # 交互式合并
gh pr merge 45 --squash # 压缩合并(Squash merge)
gh pr merge 45 --rebase # 变基合并(Rebase merge)
gh pr merge 45 --merge # 标准合并提交
gh pr merge 45 --auto # 检查通过后自动合并
更新现有 PR
gh pr edit 45 --title "新标题"
gh pr edit 45 --body "更新后的描述"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "ready-for-review"
gh pr ready 45 # 标记为就绪(移除草稿状态)
GitHub Actions 工作流管理
# 列出工作流运行
gh run list # 最近的工作流运行
gh run list --workflow=ci.yml # 特定工作流
gh run list --status=failure # 仅失败的运行
# 查看工作流运行详情
gh run view # 交互式运行选择器
gh run view 12345 # 特定运行
gh run view 12345 --web # 在浏览器中打开
# 触发工作流
gh workflow run ci.yml # 在默认分支上运行
gh workflow run ci.yml --ref feature/x # 在特定分支上运行
gh workflow run ci.yml -f key=value # 带输入参数
# 重新运行失败的作业
gh run rerun 12345 # 重新运行所有作业
gh run rerun 12345 --failed # 仅重新运行失败的作业
# 查看作业日志
gh run view 12345 --log # 完整日志输出
gh run view 12345 --log-failed # 仅失败作业的日志
# 实时观察运行过程
gh run watch # 观察当前运行
gh run watch 12345 # 观察特定运行
常用标志参考
| 标志 | 描述 |
|---|---|
-R, --repo OWNER/REPO | 目标仓库的 owner/repo |
-B, --base | PR 的基础分支 |
-H, --head | PR 的头部分支 |
-t, --title | 议题/PR 的标题 |
-b, --body | 议题/PR 的主体/描述 |
-l, --label | 标签(逗号分隔) |
-a, --assignee | 分配的用户名 |
-m, --milestone | 里程碑名称 |
--draft | 创建为草稿 PR |
--fill | 从提交消息自动填充 |
--web | 在浏览器中打开 |
-y, --yes | 跳过确认提示 |
环境变量
export GH_TOKEN="ghp_xxxx" # 个人访问令牌
export GH_HOST="github.example.com" # GitHub Enterprise 实例
export GH_REPO="owner/repo" # 默认仓库
技巧与注意事项
带 Markdown 的多行描述
创建包含 Markdown(代码块、反引号)的长描述议题或 PR 时,避免使用可能会因 shell 解释而失败的 heredoc。相反:
# 步骤 1:将描述写入临时文件(在 bash 之外)
# 步骤 2:从临时文件创建
github issue create -t "标题" -b "$(cat temp_description.txt)"
# 步骤 3:清理
rm temp_description.txt
这可以避免以下问题:
- 代码块中的反引号与命令替换冲突
- 特殊字符被 shell 解释
- heredoc 定界符冲突
从现有文件获取描述
从 Markdown 计划文件创建议题或 PR:
# 使用 body-file 标志来获取清晰的文件描述
github issue create -t "标题" --body-file docs/plans/my-plan.md
github pr create -t "标题" --body-file docs/plans/my-plan.md
详细参考
有关全面的命令选项和示例,请参阅 references/commands.md。