git 负责本地版本与分支、提交和推送；gh 负责 GitHub 上的 PR、Issue、Actions 等操作。创建 PR 不会替你提交工作区中的修改。

登录与仓库选择

gh --version
gh auth login --hostname github.com --git-protocol https --web
gh auth status
gh repo view

在仓库目录内通常会根据 Git remote 确定目标，也可以加 --repo OWNER/REPO 明确指定；OWNER、REPO 是占位符，分别替换为仓库所有者和仓库名。gh 的登录状态与 git push 的认证不是同一件事；HTTPS Git 需要使用 gh 的凭证助手时可执行 gh auth setup-git，SSH 推送则检查 SSH 配置。

登录优先使用系统凭证存储；凭证存储不可用时可能退回明文文件。不要执行 gh auth token 后把输出贴入日志或知识库。认证说明 (opens new window)

从修改到 PR

常规开发使用 feature 分支，main 只同步远程；直接提交 main 仅用于明确批准的例外。下列文件路径与分支名按实际修改替换，执行前检查工作区，不要把无关修改一起暂存：

git status --short
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c feature/docs-update

# 修改文档并验证之后，只暂存本次涉及的文件
git add -- docs/path/to/changed-guide.md
git diff --cached
git commit -m "docs: improve technical guide"
git push -u origin feature/docs-update

gh pr create \
  --repo OWNER/REPO \
  --base main \
  --head feature/docs-update \
  --title "完善技术文档" \
  --body "说明修改范围、验证方式以及尚未覆盖的内容。"

也可在已推送的 feature 分支执行 gh pr create --base main --fill，根据提交信息填写标题与正文。使用显式 --head 时，创建命令不会代替你推送该分支。PR 创建参数 (opens new window)

操作	命令示例	注意
列出 PR	gh pr list --state open	默认只列未关闭的 PR
查看内容	gh pr view 123 / gh pr diff 123	123 替换为 PR 编号
查看检查	gh pr checks 123	仓库必须配置 PR 检查才会有对应结果
检查通过后合并	gh pr merge 123 --merge	会修改远程；先确认审查、检查和仓库规则
启用自动合并	gh pr merge 123 --auto --merge	依赖仓库支持，并不等于立即合并

合并策略以仓库规则为准，--merge、--squash、--rebase 三选一，不使用 --admin 绕过保护规则。合并说明 (opens new window)

创建 PR 报 Head/Base SHA 为空或没有提交差异

这组错误不一定来自单一原因。先检查仓库、远程分支和提交差异，不要反复重试创建命令：

git remote -v
git fetch origin
git ls-remote --heads origin main feature/docs-update
git log --oneline origin/main..feature/docs-update
git diff --stat origin/main...feature/docs-update

检查结果	处理
远程没有 head 分支	确认分支和提交后，先 git push -u origin feature/docs-update
修改仍在工作区，没有新提交	检查并提交相关文件，再推送
base/head 名称或仓库不对	修正 --repo、--base、--head，跨个人 fork 时可用 用户名:分支
内容已经合并，或与 main 没有差异	不需要重复 PR；新修改应基于最新 main 开新分支

Actions 排查与定时文档检查

操作	命令示例
列出 main 最近运行	gh run list --branch main --limit 5
限定工作流	gh run list --workflow ci.yml --branch main --limit 5
查看某次运行	gh run view 123456789
只看失败步骤日志	gh run view 123456789 --log-failed
等待结束并返回失败退出码	gh run watch 123456789 --exit-status
下载文档报告	gh run download 123456789 --name docs-maintenance-report --dir reports/actions-audit
手动启动文档检查	gh workflow run docs-audit.yml --ref main
重新执行失败任务	gh run rerun 123456789 --failed

运行编号是 run ID，不是 PR 编号、job ID 或提交号。gh run list --commit 应传完整提交 SHA，例如 gh run list --commit "$(git rev-parse HEAD)"；短 SHA 可能查不到记录。gh run watch 的认证限制以当前版本手册为准；必要时改用 gh run view 查询。运行监控说明 (opens new window)

手动触发要求工作流配置了 workflow_dispatch，执行者也必须有相应权限。本项目发布工作流 ci.yml 目前监听 main/master 的 push，创建 PR 本身不会触发它；合并进 main 产生的 push 才会触发。docs-audit.yml 支持手动及每周定时检查，其报告只检查结构与复核线索，不代表文章技术结论已审核。

先定位失败阶段，再决定是否重跑：

日志特征	排查方向
getaddrinfo ENOTFOUND	检查域名与 registry，尤其锁文件中的 resolved 地址；反复重跑不能修复不可访问的依赖源
安装成功，VuePress 构建失败	查第一处构建错误、文档语法和插件；不要把所有 warning 都当成根因
构建成功，部署 push 认证失败	检查部署凭证及目标仓库权限；本地 gh 登录不能替代 Actions Secret
CLI 连不上 GitHub	检查网络和代理；不要把 token 写进命令参数或公开日志

重跑、启动工作流和合并 PR 都是远程写操作，可能触发部署或通知；确认目标后再执行。

相关记录：Git 命令、GitHub Actions。完整参数以 GitHub CLI 手册 (opens new window) 为准。