CI/CD 规范:测试、lint、发布与供应链安全

评估一条 CI/CD 流水线的质量,应依据三项客观标准:结果产出速度、结果可信度,以及流水线被攻破后的损失范围。前两项决定开发者是否信任流水线反馈:产出缓慢或偶发误报的流水线会被反复重跑直至通过,日志不再有人阅读。第三项决定仓库在单个被投毒的 action 事件中的暴露程度。

Go 工具链在此具备基础优势:go vet 与竞态检测器均为内置能力,编译与测试速度快,快速反馈是默认行为。本章以 GitHub Actions 为例;GitLab CI 思路相同,仅配置方式不同。无论采用何种平台,阶段排序与最小权限两项原则都不应让步。

流水线阶段排序

阶段顺序应固定为 fmt/vet → lint → 单元测试 → 集成测试 → 构建 → 发布,任一阶段失败即停止后续执行。 成本越低的检查应越靠前:gofmt 与 go vet 秒级完成,提前失败可避免为已注定失败的提交运行后续阶段。发布必须与主线开发解耦,始终排在最后。任何作业都不应设置 continue-on-error:为保持通过状态而忽略失败,会使该检查失去强制约束力。

CI 上的测试必须携带 -race。 Go 官方文档将数据竞争描述为并发系统中最常见、也最难排查的一类缺陷;此类问题在本地低负载环境下几乎无法复现,只有 race detector 能在每次 CI 执行中检出。应同时启用 -shuffle=on,以暴露测试之间隐式的执行顺序依赖。集成测试应使用 -count=1 显式禁用测试缓存,否则缓存结果会掩盖服务交互中的 flaky 问题,使偶发失败出现得更晚、更难定位。

go mod tidy 之后应执行 git diff --exit-code 作为最终防线。 这是一个常见错误:修改 import 后遗漏 tidy,go.sum 漂移会污染所有下游构建。加入该检查后,"遗漏 tidy"在 CI 中秒级失败,而非在其他开发者的环境中产生难以理解的报错。

矩阵构建应与 go.mod 对齐:go.mod 声明 go 1.26 时,矩阵应包含 1.26、1.27 与 stable。最低支持版本必须被实际测试,不应依赖"应该也能运行"的假设。应设置 fail-fast: false,使单个 Go 版本失败不取消其他版本的作业;否则将丢失"哪个版本损坏"这一关键信号。

覆盖率只应在一个版本上报,阈值统一收敛于 codecov.yml。矩阵中使用 if: matrix.go == 'stable' 控制 codecov/codecov-action 仅在稳定版本上传,避免同一 commit 重复上报;通过率门槛应写入仓库根目录的 codecov.yml,不应散落在 CI 脚本中。

name: Tests
on:
  push: { branches: [main] }
  pull_request:
permissions:
  contents: read                  # 默认只读,写权限按作业单独申请
jobs:
  test:
    strategy:
      fail-fast: false            # 单个 Go 版本失败不影响其他版本
      matrix:
        go: ["1.26", "1.27", "stable"]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with: { go-version: "${{ matrix.go }}" }
      - run: go mod tidy && git diff --exit-code go.mod go.sum
      - run: go test -race -shuffle=on -coverprofile=coverage.out ./...

Actions 编写规范

Go 版本应集中管理:所有 workflow 的 go-version 应来自矩阵定义或可复用的 workflow,升级 Go 只需修改一处,而非在 test/lint/security/release 四个文件中分别查找。模块缓存同理:setup-go 自 v4 起默认按 go.sum 哈希缓存模块与构建缓存,不应手写 actions/cache 重复实现该逻辑;缓存 key 设计不当可能比不缓存更慢。

concurrency 用于取消过时任务。同一 PR 连续推送多个 commit 时,旧 run 应立即取消:配置 concurrency: { group: "${{ github.workflow }}-${{ github.ref }}", cancel-in-progress: true } 可节省执行额度,并避免过时 artifact 的竞态。每个 job 应设置 timeout-minutes,否则挂起的测试默认最多消耗 360 分钟配额。

Action 引用必须固定版本:至少固定 major(如 @v6),绝不应引用 @master。 浮动引用意味着上游任何一次 push 都会原样进入流水线;固定到 major 版本既能自动获得补丁更新,又能避免 breaking change 的直接影响。要求更严格的项目应固定到具体提交 SHA,版本升级交给 Dependabot 或 Renovate。此类引用固定与依赖固定共同保证构建的可复现性。

lint 与安全扫描

golangci-lint 应在每个 PR 中执行,使用官方 golangci/golangci-lint-action 并指定 --timeout 5m。规则选择与 .golangci.yml 配置见静态检查规范;流水线层面只关注是否执行、是否超时。

govulncheck 同样必须进入 CI,发现的问题应修复,或在说明理由后显式压制。其价值在于只报告代码实际调用路径上的已知漏洞:通用 CVE 扫描器会报告依赖树中与实际执行无关的全部条目,长期积累导致告警被习惯性忽略,这比缺少扫描更危险。

CodeQL 建议启用 security-extended 套件,结果呈现在仓库 Security tab。查询套件分三档:default、security-extended(覆盖更广、精度略低)、security-and-quality(额外包含可维护性检查);配置置于 .github/codeql/codeql-config.yml,由 init / autobuild / analyze 三步组成。

SAST 层可由 gosec 与 Bearer 补充:gosec 产出 SARIF 后经 codeql-action/upload-sarif 上传,if: always() 保证扫描失败时也能提交结果;Bearer 的优势是敏感数据流分析,即密钥、PII 的泄漏路径。结果解读与定级见安全实践规范。

在静态分析之外,可增加 AI review 层:将 Claude Code / Copilot 配置为 PR reviewer,按 correctness/security 分优先级并行审查,可发现 linter 无法覆盖的逻辑错误与架构漂移。若关注成本,可仅在关键分支启用。

构建与 Docker

Dockerfile 应使用多阶段构建:builder 阶段使用完整的 golang 镜像编译,运行阶段使用 distroless 或 scratch,镜像体积与攻击面同时下降数个数量级:

FROM golang:1.27 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o /app ./cmd/app

FROM gcr.io/distroless/static-debian12
COPY --from=build /app /app
ENTRYPOINT ["/app"]

多平台构建使用 QEMU + Buildx,只保留需要的平台。linux/amd64,linux/arm64 是常见组合;每增加一个平台,构建时间线性增长,不需要的平台应移除。

PR 上只构建、不推送(push: false),用于验证 Dockerfile 的正确性;不受信代码不应具有发布镜像的通道。推送目标按需选择:GHCR 使用 GITHUB_TOKEN 即可推送,Docker Hub 需配置 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN secrets;凭据绝不应写入 workflow 文件。

镜像 tag 由 docker/metadata-action 生成:v1.2.3 会自动产生 1.2.3、1.2、1 及分支、SHA 标签,无需手工拼接字符串。sbom: true 与 provenance: mode=max 生成供应链证明,即制品签名,需要 attestations: write 与 id-token: write(OIDC)权限。权限应进一步细分:Trivy 扫描作业只授予 contents: read + security-events: write,该作业即使被攻破也无法推送镜像。

发布

发布 workflow 应只由 tag 触发,并放入配置审批的 environment。 tags: ["v*"] 意味着 PR 与普通分支推送都无法触发发布,能够创建 tag 的仅限有 push 权限的成员。发布 job 再绑定配置了 required reviewers 的 environment,在自动化之外保留人工审批环节。

name: Release
on:
  push:
    tags: ["v*"]              # PR 不触发发布
permissions:
  contents: write             # 创建 GitHub Release 所需的最小写权限
jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: release      # 可要求人工审批后才执行
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }   # 完整提交历史,用于生成 changelog
      - uses: actions/setup-go@v6
        with: { go-version: stable }
      - uses: goreleaser/goreleaser-action@v7
        with: { version: "~> v2", args: release --clean }

goreleaser 配置按项目形态分三类。CLI/程序类:核心是交叉编译多平台二进制、打包归档、生成 checksums,可选附带 Docker 镜像。库类:不产生二进制,只需要一个带 changelog 的 GitHub Release,使用跳过 build 的极简配置,或直接使用 gh release create。monorepo/多二进制类:cmd/api、cmd/worker 各自成一条 build 条目,共享同一次发布流程。

语义化版本是发布契约:tag 即发布,发布即不可变。vX.Y.Z 推送后,workflow 自动产出二进制与 changelog;对 Go 库而言,tag 推送后 module proxy 自动收录,不存在"重新发布"——发布错误只能通过新版本修正。

依赖自动化

依赖更新应自动化,minor/patch 更新聚合处理,major 更新单独开 PR。Dependabot 默认将 minor/patch 合入一个 PR 以减少噪音;major 更新可能破坏兼容性,单独成 PR 便于逐个评估。版本策略与 go.mod 的取舍见依赖管理规范。

auto-merge 的 actor 判断不是安全边界,分支保护才是。 dependabot auto-merge workflow 需要 contents: write 与 pull-requests: write 两个高危权限;if: github.actor == 'dependabot[bot]' 守卫应保留,但 github.actor 并非不可伪造。真正的安全保障是分支保护的 required status checks 与 required approvals:无论触发者是谁,合并都发生在所有检查通过之后。

Dependabot 不足时可改用 Renovate:原生 automerge(无需额外 workflow)、更灵活的分组与调度、regex manager(可更新 Dockerfile、Makefile 中的版本号)、monorepo 感知(Go workspace、多模块仓库),以及 gomodTidy——更新后自动执行 go mod tidy,与上述 git diff --exit-code 检查衔接,保证依赖固定状态不被破坏。

权限与供应链

仓库级应将 GITHUB_TOKEN 默认权限设为 read-only。 在 Actions permissions 中选择 "Read repository contents and packages permissions",取消勾选"允许 Actions 创建和批准 PR";需要写权限的 workflow 在各自的 permissions: 块中显式申请。这是纵深防御:任何一个 workflow 被攻破,在缺少显式授权时都无法写入仓库。

写权限按风险分级:contents: write(修改仓库、发布 Release)、packages: write(推送 GHCR 镜像)、pull-requests: write(合并 PR)属高危;attestations: write、id-token: write(SBOM/provenance 制品签名)、security-events: write(上传 SARIF)属中危。能以 contents: read 满足的场景,不应授予 write。

fork 的 PR 属于不可信输入。 公开仓库应将 "Fork pull request workflows from outside collaborators" 设为全部要求审批,防止陌生 fork 消耗 Actions 分钟数或读取 secrets。pull_request_target 会以基座仓库的写权限运行,历史上多起供应链事故源于用它运行不受信代码;这种用法应被禁止。

secrets 只应存入仓库设置;第三方权限令牌(如 CODECOV_TOKEN)应定期轮换。workflow 文件中出现明文凭据等同于永久泄漏。

分支保护规则是所有自动化的基础,至少包含六条:要求 PR 才能合并;至少 1 个 approval;新提交推送后撤销旧 approval,防止批准后追加提交修改代码;required status checks 覆盖全部 CI 作业;合并前分支必须为最新;管理员同样不得绕过。

速查清单

流水线阶段顺序应为 fmt/vet → lint → unit → integration → build → release,失败即停止;不使用 continue-on-error
测试必须携带 go test -race -shuffle=on;集成测试使用 -count=1 禁用缓存
使用 go mod tidy && git diff --exit-code 检测依赖漂移
测试矩阵与 go.mod 对齐,设置 fail-fast: false;覆盖率仅上报 stable,阈值写入 codecov.yml
Go 版本集中管理;缓存使用 setup-go 内置能力;配置 concurrency 取消旧 run;每个 job 设置 timeout
Action 引用至少固定 major(@vN),严格场景固定到具体提交 SHA;禁止引用 @master
golangci-lint 每个 PR 执行;govulncheck 发现的问题应修复,或在说明理由后压制
CodeQL 使用 security-extended;gosec/Bearer 的 SARIF 上传至 Security tab
Docker 采用多阶段构建;PR 只构建不推送;metadata-action 自动生成 tag;启用 SBOM/provenance 制品签名;Trivy 扫描镜像
发布仅由 v* tag 触发,绑定 environment 审批;库项目使用 gh release create 即可
依赖更新交给 Dependabot/Renovate;auto-merge 依赖分支保护,而非 actor 判断
GITHUB_TOKEN 默认只读;fork PR 需审批;pull_request_target 不运行不受信代码

流水线阶段排序

name: Tests
on:
  push: { branches: [main] }
  pull_request:
permissions:
  contents: read                  # 默认只读,写权限按作业单独申请
jobs:
  test:
    strategy:
      fail-fast: false            # 单个 Go 版本失败不影响其他版本
      matrix:
        go: ["1.26", "1.27", "stable"]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with: { go-version: "${{ matrix.go }}" }
      - run: go mod tidy && git diff --exit-code go.mod go.sum
      - run: go test -race -shuffle=on -coverprofile=coverage.out ./...

Actions 编写规范

lint 与安全扫描

构建与 Docker

Dockerfile 应使用多阶段构建:builder 阶段使用完整的 golang 镜像编译,运行阶段使用 distroless 或 scratch,镜像体积与攻击面同时下降数个数量级:

FROM golang:1.27 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o /app ./cmd/app

FROM gcr.io/distroless/static-debian12
COPY --from=build /app /app
ENTRYPOINT ["/app"]

多平台构建使用 QEMU + Buildx,只保留需要的平台。linux/amd64,linux/arm64 是常见组合;每增加一个平台,构建时间线性增长,不需要的平台应移除。

发布

name: Release
on:
  push:
    tags: ["v*"]              # PR 不触发发布
permissions:
  contents: write             # 创建 GitHub Release 所需的最小写权限
jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: release      # 可要求人工审批后才执行
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }   # 完整提交历史,用于生成 changelog
      - uses: actions/setup-go@v6
        with: { go-version: stable }
      - uses: goreleaser/goreleaser-action@v7
        with: { version: "~> v2", args: release --clean }

依赖自动化

权限与供应链

secrets 只应存入仓库设置;第三方权限令牌(如 CODECOV_TOKEN)应定期轮换。workflow 文件中出现明文凭据等同于永久泄漏。

速查清单

流水线阶段顺序应为 fmt/vet → lint → unit → integration → build → release,失败即停止;不使用 continue-on-error
测试必须携带 go test -race -shuffle=on;集成测试使用 -count=1 禁用缓存
使用 go mod tidy && git diff --exit-code 检测依赖漂移
测试矩阵与 go.mod 对齐,设置 fail-fast: false;覆盖率仅上报 stable,阈值写入 codecov.yml
Go 版本集中管理;缓存使用 setup-go 内置能力;配置 concurrency 取消旧 run;每个 job 设置 timeout
Action 引用至少固定 major(@vN),严格场景固定到具体提交 SHA;禁止引用 @master
golangci-lint 每个 PR 执行;govulncheck 发现的问题应修复,或在说明理由后压制
CodeQL 使用 security-extended;gosec/Bearer 的 SARIF 上传至 Security tab
Docker 采用多阶段构建;PR 只构建不推送;metadata-action 自动生成 tag;启用 SBOM/provenance 制品签名;Trivy 扫描镜像
发布仅由 v* tag 触发,绑定 environment 审批;库项目使用 gh release create 即可
依赖更新交给 Dependabot/Renovate;auto-merge 依赖分支保护,而非 actor 判断
GITHUB_TOKEN 默认只读;fork PR 需审批;pull_request_target 不运行不受信代码

流水线阶段排序

Actions 编写规范

lint 与安全扫描

构建与 Docker

发布

依赖自动化

权限与供应链

速查清单

Related Articles

工具链与持续更新:gopls、pkg.go.dev 与版本跟进

文档写作规范:注释、README 与 CHANGELOG

Go 生态盘点:标准库、流行库与常用工具

流水线阶段排序

Actions 编写规范

lint 与安全扫描

构建与 Docker

发布

依赖自动化

权限与供应链

速查清单

Related Articles

工具链与持续更新:gopls、pkg.go.dev 与版本跟进

文档写作规范:注释、README 与 CHANGELOG

Go 生态盘点:标准库、流行库与常用工具