Github Actions CI/CD 避坑指南：并发、权限与 Git 操作的最佳实践

donecoding
2 阅读7分钟

🚀 省流助手 (速通结论)

如果你的 GitHub Actions 工作流在 actions/checkout 或 git push 时遇到 403 权限拒绝，或者在多人同时合并 PR 时出现 Git 推送冲突，请直接使用以下三板斧：

第一斧：Token 权限配置（根治 403）

创建 Fine-grained Personal Access Token 时，务必授予：

权限项级别用途
ContentsRead and write克隆代码、推送分支和标签
Actions（可选）Read and write创建 Commit Status、触发其他工作流

第二斧：并发控制（防止多人冲突）

concurrency:
  group: release-publish
  cancel-in-progress: false

第三斧：防御性 Git 操作（保持历史干净且零冲突）

- name: Fast-forward master
  run: |
    git merge --ff-only origin/release
    git push origin master

如果你想彻底搞懂 403 的排查链路、[skip ci] 的底层原理以及为什么选择 merge 而非 rebase，请继续阅读全文。

1. 引言：自动化发布不是“能跑就行”

经过上篇文章的搭建，我们的 Monorepo 自动发布流水线已经能够正确触发、计算版本、生成标签。然而，“能跑通一次”和“能在生产环境稳定运行”之间，还隔着无数个令人抓狂的 403、冲突和死锁。

本文将聚焦于流水线健壮性的最后三块拼图：权限模型、并发控制与防御性 Git 操作。读完本文，你将对 CI/CD 中的常见“玄学报错”拥有庖丁解牛般的排查能力。

2. Token 权限模型：为什么 GITHUB_TOKEN 不够用？

很多同学会习惯性地在 actions/checkout 中直接使用默认的 ${{ secrets.GITHUB_TOKEN }}，这在普通构建任务中毫无问题。但一旦涉及 git push 操作，就可能遇到：

remote: Write access to repository not granted.
fatal: unable to access '...': The requested URL returned error: 403

2.1 默认 GITHUB_TOKEN 的限制

  • 权限范围：仅对当前仓库有效，且默认权限受工作流中 permissions 字段限制。
  • 无法跨仓库：如果你的发布流程需要推送到另一个仓库（例如 github.com/your-org/your-repo 的 Pages 分支），默认 Token 无效。
  • 分支保护绕过能力弱：即使设置了 contents: write，如果分支有严格保护规则，默认 Token 可能仍被拒绝。

2.2 自定义 Personal Access Token (PAT) 的正确姿势

推荐使用 Fine-grained token，配置步骤如下：

  1. 进入 GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens。
  2. 点击 Generate new token。
  3. Repository access：选择 Only select repositories，然后勾选你的目标仓库。
  4. Permissions：
    • Contents：必须设为 Read and write（负责代码拉取与推送）。
    • Actions：如果需要工作流内部调用 GitHub API（如创建 Commit Status），设为 Read and write。
    • Metadata：默认 Read-only 即可。
  5. 生成后复制 Token，存入仓库的 Settings → Secrets and variables → Actions，命名为 RELEASE_GITHUB_TOKEN（或其他自定义名称）。

验证 Token 是否有效（在本地执行）：

git clone https://x-access-token:YOUR_TOKEN@github.com/your-org/your-repo.git

如果能成功克隆，则 Token 权限配置正确。

2.3 403 错误排查全链路

如果在工作流中仍然遇到 403，请按以下顺序逐项检查：

排查点检查方法
Token 是否过期登录 GitHub 查看 Token 详情页，重新生成并更新 Secret
Token 权限是否包含 Contents 读写Fine-grained token 需明确勾选 Contents: Read and write
Secret 名称是否与工作流引用一致区分大小写，例如 RELEASE_GITHUB_TOKEN ≠ release_github_token
分支保护规则是否拦截检查仓库 Settings → Rules → Rulesets，若有限制，将 Bot 账号加入 Bypass 列表
远程 URL 是否包含正确的认证信息在推送步骤前加调试命令：git remote -v（Token 部分会被星号掩盖，但能看到 x-access-token）

3. 并发控制：如何避免两人同时合并造成的推送冲突？

假设两位开发者几乎同时将各自的 PR 合并到 release 分支，GitHub Actions 会触发两个并行运行的工作流。如果没有任何并发控制，以下场景极有可能发生：

  • 工作流 A 完成发布，推送了版本提交 P1 和标签 v1.0.0。
  • 工作流 B 几乎同时完成发布，也试图推送版本提交 P2 和标签 v1.0.0。
  • 由于 v1.0.0 标签已存在，工作流 B 的 git push --tags 会因冲突而失败，导致 npm 包已发布但 Git 标签未更新，状态不一致。

解决方案：引入 concurrency 配置：

concurrency:
  group: release-publish
  cancel-in-progress: false
  • group: release-publish：定义一个名为 release-publish 的并发队列。任何属于该组的工作流运行都会串行化。
  • cancel-in-progress: false：当新运行触发时，不取消已经在进行中的运行，而是让新运行进入 pending 状态排队等待。

效果：无论多少开发者同时合并 PR，发布任务永远是一个接一个执行，彻底杜绝并发冲突。

4. 防御性 Git 操作：[skip ci]、--ff-only 与合并策略的选择

4.1 [skip ci] 如何防止死循环？

在我们的工作流中，Lerna 发布后会生成一个版本提交，并推送到 release 分支。如果这个提交再次触发工作流，就会陷入无限循环。

通过在提交信息中插入 [skip ci]（或 [ci skip]、[skip actions]），GitHub Actions 会识别该关键字并跳过本次推送触发的任何工作流。

--message "chore(release): publish [skip ci]"

注意：该关键字仅对包含它的提交有效。如果后续有人基于该提交换了新的 PR 合并，工作流仍会正常触发。

4.2 --ff-only 为什么是最后一道防线？

在将 release 合并到 master 时，我们使用了：

git merge --ff-only origin/release
  • 作用：只有在 master 可以直接“快进”到 release 时才允许合并，否则报错退出。
  • 防御价值：由于发布前我们已经将 master 同步到 release，理论上 release 一定比 master 多一个发布提交，快进应该总是成功。如果有人绕过流程直接向 master 推送了代码（例如紧急 Hotfix），此时快进会失败，工作流报错，阻止了一次可能掩盖问题的自动合并提交，迫使人工介入检查。

4.3 为什么选 merge 而不是 rebase？

在同步 master 到 release 时，我们使用了 git merge --no-ff，而非 git rebase。原因如下：

操作优点缺点
Merge (--no-ff)保留完整历史，明确记录同步动作；无需强制推送历史图多一条合并线
Rebase历史完全线性，干净美观必须强制推送，有覆盖他人代码的风险；破坏协作基础

对于自动化发布流水线而言，安全性与可追溯性远比历史图的“美观”重要。因此，我们坚定地选择了 merge 方案。

5. 完整工作流中的安全配置总结

回顾整个系列，我们在工作流中嵌入了以下关键的安全与健壮性设计：

设计点配置/命令防护目标
精确触发if: github.event.pull_request.merged == true避免直接关闭 PR 误触发
并发排队concurrency: group: release-publish防止多人合并造成推送冲突
循环阻断[skip ci] 提交信息防止版本提交再次触发工作流
原子推送--no-push + 手动 git pushnpm 发布成功后才推送 Git 标签
快进断言git merge --ff-only及时发现 master 被意外修改
权限最小化Fine-grained token（仅 Contents 读写）降低 Token 泄露后的影响范围

6. 结语：从“能用”到“好用”的最后一步

至此，我们完成了 Monorepo 自动化发布流水线的全部搭建工作。两篇文章由浅入深，分别解决了：

  • 第一篇：如何搭建骨架，实现基础触发与分支同步。。
  • 第二篇：如何加固流水线，处理权限、并发与 Git 操作的边缘情况。

将这套配置部署到生产环境后，你会发现：发布不再是一件需要屏息凝神、担心手滑的“大事”，而是像呼吸一样自然的后台进程。开发者唯一要做的，就是写好代码，点下“Merge pull request”按钮。

如果你在实践过程中遇到任何新问题，欢迎在评论区交流。愿你的每一次发布都如丝般顺滑！

avatar
文章
阅读
粉丝