golang-continuous-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a Go DevOps engineer. You treat CI as a quality gate — every pipeline decision is weighed against build speed, signal reliability, and security posture.

Modes:

Setup — adding CI to a project for the first time: start with the Quick Reference table, then generate workflows in this order: test → lint → security → release. Always check latest action versions before writing YAML.
Improve — auditing or extending an existing pipeline: read current workflow files first, identify gaps against the Quick Reference table, then propose targeted additions without duplicating existing steps.

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

模式：

搭建模式——首次为项目添加CI：先参考快速参考表，再按以下顺序生成工作流：测试 → 代码检查 → 安全 → 发布。编写YAML前务必确认各Action的最新版本。
优化模式——审计或扩展现有流水线：先读取当前工作流文件，对照快速参考表找出缺口，然后针对性地添加内容，避免重复现有步骤。

Go Continuous Integration

Go持续集成

Set up production-grade CI/CD pipelines for Go projects using GitHub Actions.

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

Action Versions

Action版本

The versions shown in the examples below are reference versions that may be outdated. Before generating workflow files, search the internet for the latest stable major version of each GitHub Action used (e.g.,

actions/checkout

actions/setup-go

golangci/golangci-lint-action

codecov/codecov-action

goreleaser/goreleaser-action

, etc.). Use the latest version you find, not the one hardcoded in the examples.

以下示例中展示的版本为参考版本，可能已过时。生成工作流文件前，请先查询所使用的每个GitHub Action的最新稳定主版本（例如：

actions/checkout

、

actions/setup-go

、

golangci/golangci-lint-action

、

codecov/codecov-action

、

goreleaser/goreleaser-action

等）。请使用你找到的最新版本，而非示例中硬编码的版本。

Quick Reference

快速参考

Stage	Tool	Purpose
Test	`go test -race`	Unit + race detection
Coverage	`codecov/codecov-action`	Coverage reporting
Lint	`golangci-lint`	Comprehensive linting
Vet	`go vet`	Built-in static analysis
SAST	`gosec` , `CodeQL` , `Bearer`	Security static analysis
Vuln scan	`govulncheck`	Known vulnerability detection
Docker	`docker/build-push-action`	Multi-platform image builds
Deps	Dependabot / Renovate	Automated dependency updates
Release	GoReleaser	Automated binary releases

阶段	工具	用途
测试	`go test -race`	单元测试 + 竞态检测
覆盖率	`codecov/codecov-action`	覆盖率报告
代码检查	`golangci-lint`	全面代码检查
代码校验	`go vet`	内置静态分析
静态应用安全测试	`gosec` , `CodeQL` , `Bearer`	安全静态分析
漏洞扫描	`govulncheck`	已知漏洞检测
Docker构建	`docker/build-push-action`	多平台镜像构建
依赖管理	Dependabot / Renovate	自动化依赖更新
发布	GoReleaser	自动化二进制发布

Testing

测试

.github/workflows/test.yml

— see test.yml

Adapt the Go version matrix to match

go.mod

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"]

Use

fail-fast: false

so a failure on one Go version doesn't cancel the others.

Test flags:

```
-race
```
: CI MUST run tests with the
```
-race
```
flag (catches data races — undefined behavior in Go)
```
-shuffle=on
```
: Randomize test order to catch inter-test dependencies
```
-coverprofile
```
: Generate coverage data
```
git diff --exit-code
```
: Fails if
```
go mod tidy
```
changes anything

.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
```
修改了任何内容则失败

Coverage Configuration

覆盖率配置

CI SHOULD enforce code coverage thresholds. Configure thresholds in

codecov.yml

at the repo root — see codecov.yml

CI应强制代码覆盖率阈值。在仓库根目录的

codecov.yml

中配置阈值——查看 codecov.yml

Integration Tests

集成测试

.github/workflows/integration.yml

— see integration.yml

Use

-count=1

to disable test caching — cached results can hide flaky service interactions.

.github/workflows/integration.yml

— 查看 integration.yml

使用

-count=1

禁用测试缓存——缓存的结果可能会掩盖不稳定的服务交互问题。

Linting

代码检查

golangci-lint

MUST be run in CI on every PR.

.github/workflows/lint.yml

— see lint.yml

golangci-lint

必须在CI中对每个PR运行。

.github/workflows/lint.yml

— 查看 lint.yml

golangci-lint Configuration

golangci-lint配置

Create

.golangci.yml

at the root of the project. See the

samber/cc-skills-golang@golang-linter

skill for the recommended configuration.

在项目根目录创建

.golangci.yml

。推荐配置可参考

samber/cc-skills-golang@golang-linter

技能。

Security & SAST

安全与静态应用安全测试

.github/workflows/security.yml

— see security.yml

CI MUST run

govulncheck

. It only reports vulnerabilities in code paths your project actually calls — unlike generic CVE scanners. CodeQL results appear in the repository's Security tab. Bearer is good at detecting sensitive data flow issues.

.github/workflows/security.yml

— 查看 security.yml

CI必须运行

govulncheck

。它仅报告项目实际调用的代码路径中的漏洞——不同于通用CVE扫描器。CodeQL结果显示在仓库的安全标签页中。Bearer擅长检测敏感数据流问题。

CodeQL Configuration

CodeQL配置

Create

.github/codeql/codeql-config.yml

to use the extended security query suite — see codeql-config.yml

Available query suites:

default: Standard security queries
security-extended: Extra security queries with slightly lower precision
security-and-quality: Security queries plus maintainability and reliability checks

创建

.github/codeql/codeql-config.yml

以使用扩展安全查询套件——查看 codeql-config.yml

可用的查询套件：

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

Container Image Scanning

容器镜像扫描

If the project produces Docker images, Trivy container scanning is included in the Docker workflow — see docker.yml

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

Dependency Management

依赖管理

Dependabot

.github/dependabot.yml

— see dependabot.yml

Minor/patch updates are grouped into a single PR. Major updates get individual PRs since they may have breaking changes.

.github/dependabot.yml

— 查看 dependabot.yml

次要/补丁更新会合并到单个PR中。主版本更新会生成单独的PR，因为它们可能包含破坏性变更。

Auto-Merge for Dependabot

Dependabot自动合并

.github/workflows/dependabot-auto-merge.yml

— see dependabot-auto-merge.yml

Security warning: This workflow requires
contents: write
and
pull-requests: write
— these are elevated permissions that allow merging PRs and modifying repository content. The
if: github.actor == 'dependabot[bot]'
guard restricts execution to Dependabot only. Do not remove this guard. Note that
github.actor
checks are not fully spoof-proof — branch protection rules are the real safety net. Ensure branch protection is configured (see Repository Security Settings) with required status checks and required approvals so that auto-merge only succeeds after all checks pass, regardless of who triggered the workflow.

.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 (alternative)

Renovate（替代方案）

Renovate is a more mature and configurable alternative to Dependabot. It supports automerge natively, grouping, scheduling, regex managers, and monorepo-aware updates. If Dependabot feels too limited, Renovate is the go-to choice.

Install the Renovate GitHub App, then create

renovate.json

at the repo root — see renovate.json

Key advantages over Dependabot:

gomodTidy
: Automatically runs
```
go mod tidy
```
after updates
Native automerge: No separate workflow needed
Better grouping: More flexible rules for grouping PRs
Regex managers: Can update versions in Dockerfiles, Makefiles, etc.
Monorepo support: Handles Go workspaces and multi-module repos

Renovate是Dependabot的更成熟、可配置性更强的替代方案。它原生支持自动合并、分组、调度、正则管理器，以及感知单体仓库的更新。如果Dependabot功能不足，Renovate是首选。

安装 Renovate GitHub App，然后在仓库根目录创建

renovate.json

——查看 renovate.json

相对于Dependabot的主要优势：

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

Release Automation

发布自动化

GoReleaser automates binary builds, checksums, and GitHub Releases. The configuration varies significantly depending on the project type.

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

Release Workflow

发布工作流

.github/workflows/release.yml

— see release.yml

Security warning: This workflow requires
contents: write
to create GitHub Releases. It is restricted to tag pushes (
tags: ["v*"]
) so it cannot be triggered by pull requests or branch pushes. Only users with push access to the repository can create tags.

.github/workflows/release.yml

— 查看 release.yml

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

GoReleaser for CLI/Programs

用于CLI/程序的GoReleaser

Programs need cross-compiled binaries, archives, and optionally Docker images.

.goreleaser.yml

— see goreleaser-cli.yml

程序需要跨编译二进制文件、归档文件，可选Docker镜像。

.goreleaser.yml

— 查看 goreleaser-cli.yml

GoReleaser for Libraries

用于库的GoReleaser

Libraries don't produce binaries — they only need a GitHub Release with a changelog. Use a minimal config that skips the build.

.goreleaser.yml

— see goreleaser-lib.yml

For libraries, you may not even need GoReleaser — a simple GitHub Release created via the UI or

gh release create

is often sufficient.

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

.goreleaser.yml

— 查看 goreleaser-lib.yml

对于库，你甚至可能不需要GoReleaser——通过UI或

gh release create

创建简单的GitHub Release通常就足够了。

GoReleaser for Monorepos / Multi-Binary

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

When a repository contains multiple commands (e.g.,

cmd/api/

cmd/worker/

.goreleaser.yml

— see goreleaser-monorepo.yml

当仓库包含多个命令时（例如：

cmd/api/

、

cmd/worker/

）。

.goreleaser.yml

— 查看 goreleaser-monorepo.yml

Docker Build & Push

Docker构建与推送

For projects that produce Docker images. This workflow builds multi-platform images, generates SBOM and provenance attestations, pushes to both GitHub Container Registry (GHCR) and Docker Hub, and includes Trivy container scanning.

.github/workflows/docker.yml

— see docker.yml

Security warning: Permissions are scoped per job: the
container-scan
job only gets
contents: read
+
security-events: write
, while the
docker
job gets
packages: write
(to push to GHCR) and
attestations: write
+
id-token: write
(for provenance/SBOM signing). This ensures the scan job cannot push images even if compromised. The
push
flag is set to
false
on pull requests so untrusted code cannot publish images. The
DOCKERHUB_USERNAME
and
DOCKERHUB_TOKEN
secrets must be configured in the repository secrets settings — never hardcode credentials.

Key details:

QEMU + Buildx: Required for multi-platform builds (
```
linux/amd64,linux/arm64
```
). Remove platforms you don't need.
push: false
on PRs: Images are built but never pushed on pull requests — this validates the Dockerfile without publishing untrusted code.
Metadata action: Automatically generates semver tags (
```
v1.2.3
```
→
```
1.2.3
```
,
```
1.2
```
,
```
1
```
), branch tags (
```
main
```
), and SHA tags.
Provenance + SBOM:
```
provenance: mode=max
```
and
```
sbom: true
```
generate supply chain attestations. These require
```
attestations: write
```
and
```
id-token: write
```
permissions.
Dual registry: Pushes to both GHCR (using
```
GITHUB_TOKEN
```
, no extra secret needed) and Docker Hub (requires
```
DOCKERHUB_USERNAME
```
+
```
DOCKERHUB_TOKEN
```
secrets). Remove the Docker Hub login and image line if not needed.
Trivy: Scans the built image for CRITICAL and HIGH vulnerabilities and uploads results to the Security tab.
Adapt the image names and registries to your project. For GHCR-only, remove the Docker Hub login step and the
```
docker.io/
```
line from
```
images:
```
.

适用于生成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
: 拉取请求中仅构建镜像但不推送——这会验证Dockerfile，但不会发布不可信代码。
元数据Action: 自动生成语义化版本标签（
```
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登录步骤和
```
images:
```
中的
```
docker.io/
```
行。
Trivy: 扫描构建的镜像中的CRITICAL和HIGH漏洞，并将结果上传到安全标签页。
根据项目调整镜像名称和注册表。如果仅使用GHCR，移除Docker Hub登录步骤和
```
images:
```
中的
```
docker.io/
```
行。

Repository Security Settings

仓库安全设置

After creating workflow files, ALWAYS tell the developer to configure GitHub repository settings (branch protection, workflow permissions, secrets, environments) — see repo-security.md

创建工作流文件后，务必告知开发者配置GitHub仓库设置（分支保护、工作流权限、机密、环境）——查看 repo-security.md

Common Mistakes

常见错误

Mistake	Fix
Missing `-race` in CI tests	Always use `go test -race`
No `-shuffle=on`	Randomize test order to catch inter-test dependencies
Caching integration test results	Use `-count=1` to disable caching
`go mod tidy` not checked	Add `go mod tidy && git diff --exit-code` step
Missing `fail-fast: false`	One Go version failing shouldn't cancel other jobs
Not pinning action versions	GitHub Actions MUST use pinned major versions (e.g. `@vN` , not `@master` )
No `permissions` block	Follow least-privilege per job
Ignoring govulncheck findings	Fix or suppress with justification

错误	修复方案
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结果	修复或提供理由后忽略

golang-continuous-integration

Original

Translation

Go Continuous Integration

Go持续集成

Action Versions

Action版本

Quick Reference

快速参考

Testing

测试

Coverage Configuration

覆盖率配置

Integration Tests

集成测试

Linting

代码检查

golangci-lint Configuration

golangci-lint配置

Security & SAST

安全与静态应用安全测试

CodeQL Configuration

CodeQL配置

Container Image Scanning

容器镜像扫描

Dependency Management

依赖管理

Dependabot

Dependabot

Auto-Merge for Dependabot

Dependabot自动合并

Renovate (alternative)

Renovate（替代方案）

Release Automation

发布自动化

Release Workflow

发布工作流

GoReleaser for CLI/Programs

用于CLI/程序的GoReleaser

GoReleaser for Libraries

用于库的GoReleaser

GoReleaser for Monorepos / Multi-Binary

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

Docker Build & Push

Docker构建与推送

Repository Security Settings

仓库安全设置

Common Mistakes

常见错误

Related Skills

相关技能