golang-continuous-integration

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

模式：

• 设置 — 首次为项目添加 CI：从快速参考表开始，然后按以下顺序生成工作流：测试 → lint → 安全 → 发布。每个 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	覆盖率报告
Lint	golangci-lint	综合 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 版本矩阵，使其与 go.mod 相匹配：

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

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

Go 1.27 将 Darwin 的最低版本提升至 macOS 13（Ventura）。macos-latest/macos-14+ 运行器不受影响；只有项目仍需要较旧的 macos-12 运行器时，才将其固定为该版本，并注意它已无法使用 Go 1.27 工具链构建。

测试标志：

• -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 禁用测试缓存——缓存结果可能会掩盖不稳定的服务交互。

---

Lint

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

golangci-lint 配置

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

---

安全与 SAST

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

CI 必须运行 govulncheck——与通用 CVE 扫描器不同，它只会报告项目实际调用的代码路径中的漏洞。

• CodeQL 结果会显示在仓库的 Security 选项卡中。
• 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 App，然后在仓库根目录创建 renovate.json — 参见 renovate.json

相较于 Dependabot 的主要优势：

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

---

发布自动化

GoReleaser 可自动完成二进制文件构建、校验和生成和 GitHub Releases 创建。配置会因项目类型而有很大差异。

发布工作流

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

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

面向 CLI/程序的 GoReleaser

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

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

面向库的 GoReleaser

库不会生成二进制文件 — 只需要一个包含变更日志的 GitHub Release。请使用跳过构建的最简配置。

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

对于库，甚至可能不需要 GoReleaser — 通常通过界面创建简单的 GitHub Release，或使用 gh release create 就足够了。

面向单体仓库/多二进制文件的 GoReleaser

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

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

Docker 构建与推送

适用于会生成 Docker 镜像的项目。此工作流会构建多平台镜像、生成 SBOM 和来源证明证明，并推送到 GitHub Container Registry（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）所必需。移除不需要的平台。
• PR 中的 push: false：拉取请求中只构建镜像，不会推送——这样可以验证 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：扫描已构建的镜像，查找 CRITICAL 和 HIGH 漏洞，并将结果上传到 Security 选项卡。
• 根据项目调整镜像名称和注册表。若仅使用 GHCR，请移除 Docker Hub 登录步骤，以及 images: 中的 docker.io/ 行。

---

仓库安全设置

仓库安全设置（分支保护、工作流权限、密钥、环境）构成 CI 流水线的安全基础，相关说明见 repo-security.md。

---

AI 驱动的代码审查

将 AI Agent 添加为 PR 审查者，与传统静态分析并行运行。加载此技能插件后，Agent 会根据各审查领域应用相关的 Go 技能，从而发现代码检查工具无法检测的架构偏离、逻辑错误、缺失的错误上下文和并发风险。

成本提示： AI 审查 Agent 会针对每个 PR 并发运行。为控制成本，请移除不需要的作业，或将 PR 触发筛选条件收紧为仅针对特定分支。

下面的每个小节都是针对特定审查者生成的产物——链接的资源文件会在 CI 运行器上运行，而不是在开发者的本地运行环境中运行，因此其中的工具名称和权限标志会有意采用字面写法，而非能力描述。

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 App 集成通过 /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 版本测试失败不应取消其他任务
未固定操作版本	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 技能。