golang-continuous-integration

角色： 你是一名 Go DevOps 工程师。你将 CI 视为质量门——每个流水线决策都需权衡构建速度、信号可靠性和安全态势。

模式：

• 设置——首次为项目添加 CI：从快速参考表开始，然后按以下顺序生成工作流：测试 → 代码检查 → 安全 → 发布。优先使用每个 GitHub Action 的最新稳定主版本。
• 改进——审计或扩展现有流水线：首先读取当前工作流文件，对照快速参考表识别差距，然后提出有针对性的补充，不重复现有步骤。

依赖项：

• goreleaser：go install github.com/goreleaser/goreleaser/v2@latest
• gh：brew install gh

Go 持续集成

使用 GitHub Actions 为 Go 项目设置生产级 CI/CD 流水线。

Action 版本

以下示例中的版本是参考版本，可能已过时。GitHub Actions 发布频繁——每个 action 的当前主版本（actions/checkout、actions/setup-go、golangci/golangci-lint-action、codecov/codecov-action、goreleaser/goreleaser-action 等）可能与这里显示的不同。

快速参考

阶段	工具	目的
测试	go test -race	单元测试 + 竞态检测
覆盖率	codecov/codecov-action	覆盖率报告
代码检查	golangci-lint	全面代码检查
Vet	go vet	内置静态分析
SAST	gosec、CodeQL、Bearer	安全静态分析
漏洞扫描	govulncheck	已知漏洞检测
Docker	docker/build-push-action	多平台镜像构建
依赖项	Dependabot / Renovate	自动化依赖更新
发布	GoReleaser	自动化二进制发布
AI 审查	Claude Code / Copilot	AI 驱动的 PR 审查

---

测试

.github/workflows/test.yml——参见 test.yml

根据 go.mod 调整 Go 版本矩阵：

go 1.23   → matrix: ["1.23", "1.24", "1.25", "1.26", "stable"]
go 1.24   → matrix: ["1.24", "1.25", "1.26", "stable"]
go 1.25   → matrix: ["1.25", "1.26", "stable"]
go 1.26   → matrix: ["1.26", "stable"]

使用 fail-fast: false，这样某个 Go 版本的失败不会取消其他版本。

测试标志：

• -race：CI 必须使用 -race 标志运行测试（捕获数据竞争——Go 中的未定义行为）
• -shuffle=on：随机化测试顺序以捕获测试间依赖
• -coverprofile：生成覆盖率数据
• git diff --exit-code：如果 go mod tidy 更改了任何内容则失败

覆盖率配置

CI 应强制执行代码覆盖率阈值。在仓库根目录的 codecov.yml 中配置阈值——参见 codecov.yml

---

集成测试

.github/workflows/integration.yml——参见 integration.yml

使用 -count=1 禁用测试缓存——缓存的结果可能隐藏不稳定的服务交互。

---

代码检查

golangci-lint 必须在 CI 中对每个 PR 运行。.github/workflows/lint.yml——参见 lint.yml

golangci-lint 配置

在项目根目录创建 .golangci.yml。有关推荐配置，请参见 samber/cc-skills-golang@golang-lint 技能。

---

安全与 SAST

.github/workflows/security.yml——参见 security.yml

CI 必须运行 govulncheck。它只报告项目实际调用的代码路径中的漏洞——与通用 CVE 扫描器不同。CodeQL 结果出现在仓库的“安全”选项卡中。Bearer 擅长检测敏感数据流问题。

CodeQL 配置

创建 .github/codeql/codeql-config.yml 以使用扩展安全查询套件——参见 codeql-config.yml

可用的查询套件：

• default：标准安全查询
• security-extended：额外的安全查询，精度略低
• security-and-quality：安全查询加上可维护性和可靠性检查

容器镜像扫描

如果项目生成 Docker 镜像，Docker 工作流中包含 Trivy 容器扫描——参见 docker.yml

---

依赖管理

Dependabot

.github/dependabot.yml——参见 dependabot.yml

次要/补丁更新合并到一个 PR 中。主要更新获得单独的 PR，因为它们可能包含破坏性更改。

Dependabot 自动合并

.github/workflows/dependabot-auto-merge.yml——参见 dependabot-auto-merge.yml

安全警告： 此工作流需要 contents: write 和 pull-requests: write——这些是提升的权限，允许合并 PR 和修改仓库内容。if: github.actor == 'dependabot[bot]' 守卫将执行限制为仅 Dependabot。请勿移除此守卫。请注意，github.actor 检查并非完全防欺骗——分支保护规则才是真正的安全网。确保配置了分支保护（参见仓库安全设置），包含所需的状态检查和所需的批准，以便自动合并仅在所有检查通过后成功，无论谁触发了工作流。

Renovate（替代方案）

Renovate 是比 Dependabot 更成熟、更可配置的替代方案。它原生支持自动合并、分组、调度、正则表达式管理器以及感知单体仓库的更新。如果 Dependabot 感觉过于受限，Renovate 是首选。

安装 Renovate GitHub 应用，然后在仓库根目录创建 renovate.json——参见 renovate.json

与 Dependabot 相比的主要优势：

• gomodTidy：更新后自动运行 go mod tidy
• 原生自动合并：无需单独的工作流
• 更好的分组：更灵活的分组 PR 规则
• 正则表达式管理器：可以更新 Dockerfile、Makefile 等中的版本
• 单体仓库支持：处理 Go 工作区和多模块仓库

---

发布自动化

GoReleaser 自动化二进制构建、校验和和 GitHub 发布。配置因项目类型而异。

发布工作流

.github/workflows/release.yml——参见 release.yml

安全警告： 此工作流需要 contents: write 以创建 GitHub 发布。它仅限于标签推送（tags: ["v*"]），因此不能由拉取请求或分支推送触发。只有具有仓库推送权限的用户才能创建标签。

用于 CLI/程序的 GoReleaser

程序需要交叉编译的二进制文件、归档文件以及可选的 Docker 镜像。

.goreleaser.yml——参见 goreleaser-cli.yml

用于库的 GoReleaser

库不生成二进制文件——它们只需要带有变更日志的 GitHub 发布。使用跳过构建的最小配置。

.goreleaser.yml——参见 goreleaser-lib.yml

对于库，您甚至可能不需要 GoReleaser——通过 UI 或 gh release create 创建的简单 GitHub 发布通常就足够了。

用于单体仓库/多二进制文件的 GoReleaser

当仓库包含多个命令时（例如 cmd/api/、cmd/worker/）。

.goreleaser.yml——参见 goreleaser-monorepo.yml

Docker 构建与推送

适用于生成 Docker 镜像的项目。此工作流构建多平台镜像，生成 SBOM 和出处证明，推送到 GitHub 容器注册表（GHCR）和 Docker Hub，并包含 Trivy 容器扫描。

.github/workflows/docker.yml——参见 docker.yml

安全警告： 权限按作业范围划分：container-scan 作业仅获得 contents: read + security-events: write，而 docker 作业获得 packages: write（用于推送到 GHCR）和 attestations: write + id-token: write（用于出处/SBOM 签名）。这确保即使扫描作业被攻破，也无法推送镜像。push 标志在拉取请求上设置为 false，因此不受信任的代码无法发布镜像。DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN 密钥必须在仓库密钥设置中配置——切勿硬编码凭据。

关键细节：

• QEMU + Buildx：多平台构建所需（linux/amd64,linux/arm64）。移除不需要的平台。
• push: false on PRs：镜像在拉取请求上构建但从不推送——这验证了 Dockerfile 而不发布不受信任的代码。
• 元数据操作：自动生成 semver 标签（v1.2.3 → 1.2.3、1.2、1）、分支标签（main）和 SHA 标签。
• 出处 + SBOM：provenance: mode=max 和 sbom: true 生成供应链证明。这些需要 attestations: write 和 id-token: write 权限。
• 双注册表：推送到 GHCR（使用 GITHUB_TOKEN，无需额外密钥）和 Docker Hub（需要 DOCKERHUB_USERNAME + DOCKERHUB_TOKEN 密钥）。如果不需要，请移除 Docker Hub 登录和镜像行。
• Trivy：扫描构建的镜像以查找严重和高危漏洞，并将结果上传到“安全”选项卡。
• 根据您的项目调整镜像名称和注册表。如果仅使用 GHCR，请移除 Docker Hub 登录步骤和 images: 中的 docker.io/ 行。

---

仓库安全设置

仓库安全设置（分支保护、工作流权限、密钥、环境）构成了 CI 流水线的安全基础——这些在 repo-security.md 中有文档说明。

---

AI 驱动的代码审查

将 AI 代理添加为 PR 审查者，与传统的静态分析一起使用。当加载此技能插件时，代理会根据审查领域应用相关的 Go 技能——捕获代码检查器无法检测到的架构漂移、逻辑错误、缺失的错误上下文和并发危险。

成本说明： AI 审查代理在每个 PR 上并发运行。为控制成本，请移除不需要的作业，或将 PR 触发过滤器提升到特定分支。

Claude Code

.github/workflows/ai-review.yml——参见 claude-code-review.yml

该工作流运行并行作业，每个作业针对一组审查领域和优先级：

作业	领域	优先级
quality	代码风格、命名、文档、设计模式	建议优先
correctness	错误处理、代码安全、并发	阻塞优先
security	安全、依赖项	阻塞优先
quality-depth	测试、性能、可观测性、现代化	混合

根据项目可能相关的其他技能：golang-cli、golang-context、golang-data-structures、golang-database、golang-dependency-injection 或任何特定于库的技能。

Claude Code GitHub 应用集成通过 /install-github-app 命令配置，该命令设置所需的 API 密钥。

GitHub Copilot

将技能复制到您的仓库中，然后将 copilot-review-instructions.md 附加到 .github/copilot-instructions.md：

npx skills add https://github.com/samber/cc-skills-golang --agent github-copilot --skill '*' -y --copy
ln -s .agents .copilot

---

常见错误

错误	修复
CI 测试中缺少 -race	始终使用 go test -race
没有 -shuffle=on	随机化测试顺序以捕获测试间依赖
缓存集成测试结果	使用 -count=1 禁用缓存
未检查 go mod tidy	添加 go mod tidy && git diff --exit-code 步骤
缺少 fail-fast: false	一个 Go 版本失败不应取消其他作业
未固定 action 版本	GitHub Actions 必须使用固定的主版本（例如 @vN，而不是 @master）
没有 permissions 块	遵循每个作业的最小权限原则
忽略 govulncheck 发现	修复或提供理由后抑制
CI 中没有 AI 审查	添加 Claude Code 或 Copilot 审查——捕获静态分析遗漏的逻辑、安全和架构问题

相关技能

参见 samber/cc-skills-golang@golang-lint、samber/cc-skills-golang@golang-security、samber/cc-skills-golang@golang-testing、samber/cc-skills-golang@golang-dependency-management、samber/cc-skills-golang@golang-modernize 技能。