为 Go 项目搭建或改进 GitHub Actions…

当需要为 Golang 项目首次搭建或优化 GitHub Actions CI/CD 流水线、编写或修复 .github/workflows/*.yml、添加 linter/安全扫描任务、接入依赖更新机器人或增加质量门禁时使用。

适用场景

解决思路

1. 按 Setup 模式首次搭建时，先参考 Quick Reference 表，再按 test → lint → security → release 的顺序生成 workflow；Improve 模式先读取现有 workflow 文件，对照 Quick Reference 表找出缺口，再做针对性补充而不重复已有步骤。
2. 测试 workflow 使用 go test -race 运行单元测试并检测数据竞争，加 -shuffle=on 随机化测试顺序以发现测试间依赖，加 -coverprofile 生成覆盖率数据，并用 go mod tidy && git diff --exit-code 检查 go.mod 是否整洁。
3. 根据 go.mod 中的 Go 版本设置测试矩阵（如 go 1.25 → matrix: ["1.25", "1.26", "1.27", "stable"]），并设置 fail-fast: false，避免某个 Go 版本失败取消其他任务。
4. 在仓库根目录创建 codecov.yml 配置覆盖率阈值，并在 CI 中通过 codecov/codecov-action 强制覆盖率门禁。
5. 集成测试 workflow 使用 -count=1 禁用测试缓存，避免缓存结果掩盖不稳定的服务交互。
6. 在每个 PR 上通过 golangci-lint 运行 lint（使用 golangci/golangci-lint-action），并在项目根目录创建 .golangci.yml 配置文件。
7. 安全 workflow 必须运行 govulncheck（只报告项目实际调用代码路径中的漏洞），并接入 CodeQL（结果出现在仓库 Security 标签页）和 Bearer（检测敏感数据流问题）。
8. 创建 .github/codeql/codeql-config.yml 使用扩展安全查询套件，可选 default、security-extended、security-and-quality 三种查询套件。
9. 若项目产出 Docker 镜像，在 Docker workflow 中集成 Trivy 容器扫描。
10. 创建 .github/dependabot.yml：将 minor/patch 更新合并为单个 PR，major 更新生成独立 PR（可能含破坏性变更）。
11. 如需 Dependabot 自动合并，添加 .github/workflows/dependabot-auto-merge.yml，保留 if: github.actor == 'dependabot[bot]' 守卫，并配置分支保护规则（必需状态检查与必需审批）作为真正的安全网。
12. 或使用 Renovate 作为更成熟可配置的替代：安装 Renovate GitHub App 并在仓库根目录创建 renovate.json，利用其 gomodTidy（更新后自动运行 go mod tidy）、原生 automerge、更灵活的分组、regex managers（更新 Dockerfile/Makefile 中的版本）和 monorepo 支持。
13. 发布自动化使用 GoReleaser：release workflow 限制为 tag 推送（tags: ["v*"]）并需要 contents: write 权限；CLI/程序使用交叉编译二进制、归档和可选 Docker 镜像的 .goreleaser.yml；库使用跳过 build 的最小配置（或直接用 gh release create）；monorepo/多二进制使用对应配置。
14. Docker 构建推送 workflow：使用 QEMU + Buildx 做多平台构建（linux/amd64,linux/arm64），PR 上设置 push: false 不推送镜像，用 metadata action 自动生成 semver/branch/SHA 标签，设置 provenance: mode=max 和 sbom: true 生成供应链证明（需 attestations: write 和 id-token: write 权限），同时推送到 GHCR（用 GITHUB_TOKEN）和 Docker Hub（需 DOCKERHUB_USERNAME + DOCKERHUB_TOKEN secrets），并按 job 最小权限划分（container-scan 仅 contents: read + security-events: write，docker job 才拿 packages: write）。
15. 配置仓库安全设置：分支保护、workflow 权限、secrets、environments（详见 repo-security.md）。
16. 接入 AI 驱动代码审查：Claude Code 通过 /install-github-app 配置 API secrets 并添加 .github/workflows/ai-review.yml，运行并行 job（quality、correctness、security、quality-depth）分别覆盖不同审查领域与优先级；GitHub Copilot 则用 npx skills add https://github.com/samber/cc-skills-golang --agent github-copilot --skill '*' -y --copy 复制 skills 并 ln -s .agents .copilot，再把 copilot-review-instructions.md 追加到 .github/copilot-instructions.md。
17. 避免常见错误：CI 测试必须加 -race；加 -shuffle=on；集成测试用 -count=1；检查 go mod tidy；设置 fail-fast: false；GitHub Actions 必须固定主版本（如 @vN 而非 @master）；每个 job 配置最小权限 permissions 块；处理或带理由抑制 govulncheck 发现；在 CI 中加入 AI 审查。
18. 使用最新稳定主版本的 GitHub Action（actions/checkout、actions/setup-go、golangci/golangci-lint-action、codecov/codecov-action、goreleaser/goreleaser-action 等），示例中的版本可能已过时。
19. 安装依赖工具：goreleaser 用 go install github.com/goreleaser/goreleaser/v2@latest 或 brew install goreleaser；gh 用 brew install gh。

适用边界 · 注意事项

• 不用于选择或解读安全发现（应使用 samber/cc-skills-golang@golang-security 技能）。
• 不用于选择、升级或审计依赖版本（应使用 samber/cc-skills-golang@golang-dependency-management 技能）。
• 不适用于非 GitHub Actions 的 CI 平台或非 Go 项目。