流水线与自动化：从 workflow 到 artifact 与 runner

0. 元信息

• 主题路径：docs/topics/ci-cd-and-release/subtopics/pipeline-and-automation/README.md
• 主分类：工程技术
• 辅助分类：安全与可靠性
• 适合对象：完成父主题前置，能写 Dockerfile 和 shell 的开发者
• 建议周期：5～8 天，每天 1.5～2 小时
• 前置知识：父主题 §0 列举的前置主题
• 最终目标：能独立写出可重复、可扫描、可发布的 GitHub Actions / GitLab CI pipeline，留存 workflow YAML、runner log 与 artifact 证据

1. 学习路线

workflow 语法（on / jobs / steps / runs-on / needs）
  → matrix / cache / concurrency / artifact
  → self-hosted runner / act 本地跑
  → OIDC 与 secret 管理
  → 扫描与 SBOM 输出（trivy / syft）
  → cosign 签名 + push 到 OCI registry

2. 阶段周数分配

精简子主题不固定周数。按概念、正常路径、失败路径、综合实验四段推进，共 5～8 天。

3. 九阶段表

4. 第一周任务

精简子主题省略逐日表。每天只引入一个变量；先跑正常路径，再做四类失败实验。Day 1 必须明确 runner、permissions 与 secret 来源。

5. 阶段通用验收

采用父主题 §5；本页额外要求保存 workflow YAML、runner log 链接、artifact 下载链接、cache 命中日志、cosign verify 输出与清理命令。

6. 最终验收

完成 1 条生产级 workflow（build / test / scan / sign / push / artifact）、至少 4 类失败实验、一次本地 act 重放、一次 OIDC 部署演练，并用 10 分钟解释 jobs、cache、matrix、OIDC 的边界。

7. 综合项目

把本页产出合入父主题首选项目：GitHub Actions → GHCR → k8s Argo Rollouts 金丝雀发布全链路。单独交付时，提供 workflow 文件、act 重放脚本、notes/retrospective.md。

本主题贡献

本主题把 GitHub Actions 当作 CI 引擎：workflow DAG、matrix/cache/concurrency、self-hosted runner、OIDC 短期凭证、SBOM 生成与 cosign 签名串成可重复、可回放、可验证的流水线。

职责（3 项）

1. 设计 workflow YAML（on / jobs / steps / runs-on / needs / if / env / permissions），画 jobs 之间的 DAG，能解释 ${{ }} 表达式与 shell 变量边界、为什么 permissions: 默认值要在 job 顶部显式声明、为什么 pull_request_target 暴露 secrets 给 fork PR 是反模式；
2. 用 actions/cache@v4 + hashfiles('**/go.sum') 设计 lockfile 级缓存，用 buildx cache-to/cache-from (type=gha / type=registry) 做 multi-platform（amd64+arm64）缓存，能解释为什么 key 含 lockfile 才命中、为什么 @sha256:... 锁 commit 而非 @main；
3. 用 permissions: id-token: write + cloud trust policy（sub 限定 repo + workflow）拿 OIDC 短期凭证替代 long-lived AWS access key，用 cosign sign --keyless + Rekor transparency log 签 image。

交付物（4 项）

1. 生产级 workflow YAML（build / test / scan / sign / push / artifact 完整 DAG），含 concurrency group 自动取消旧 run；
2. act 本地重放脚本（nektos/act，Apache-2.0）+ runner log 链接 + artifact 下载链接；
3. SBOM（Anchore Syft 输出 SPDX）+ cosign verify 输出 + grype sbom: 漏洞扫描结果，artifact 同时含 image + SBOM + signature；
4. OIDC 部署演练（aws-actions/configure-aws-credentials@v4）的 cloud audit log 截图，证明 role 临时凭证而非 long-lived key。

指标（3 项）

1. build cache 命中率 ≥ 80%（key 含 lockfile hash 后）；
2. cosign verify 在 deploy gate 阻断伪造制品率 = 100%；
3. 同 commit → 同 image digest 比例 = 100%（锁 base digest、build context 时间戳、org.opencontainers.image.revision）。

8. 推荐开源资料

GitHub Actions 官方文档作主线；act 仓库（nektos/act，Apache-2.0）作本地 runner；buildx（docker/buildx，Apache-2.0）作多平台；aquasecurity/trivy-action（Apache-2.0）作扫描；sigstore/cosign-installer（Apache-2.0）作签名；actions-runner-controller（GitHub，Apache-2.0）作 k8s 自托管 runner。复制前核对当前 LICENSE。

9. 学习资料汇聚（v0.3 自包含）

9.1 背景与动机

CI 把 commit 变成可发布制品。流水线核心做四件事：build（编译/打包/构建 image）、test（单元/集成/e2e）、scan（漏洞/依赖/配置）、ship（签名/推送/产出 artifact）。每件事都必须可重复、可追溯、可回放。

GitHub Actions 用 YAML 描述 steps，依赖 Docker 容器或 JS 脚本作为 step；GitLab CI 用 .gitlab-ci.yml，依赖 Docker/Ruby 镜像；CircleCI 用 config.yml，依赖 executor。三者语法略有差异，但模型都是 event-driven + DAG + cache + artifact。

今天流水线工程化的关键不是「跑得通」，而是「可重复、可签名、可回放」：同 commit 必须产出同 digest；image 必须带 SBOM 和 provenance；secret 不能用 long-lived key；runner 必须可控。

9.2 概念地图

flowchart LR
  Event[on: push / PR / tag / workflow_dispatch] --> Jobs
  Jobs --> Job1[build]
  Jobs --> Job2[test]
  Jobs --> Job3[scan]
  Jobs --> Job4[sign]
  Jobs --> Job5[push]
  Job1 --> Artifact[artifact]
  Job2 --> Artifact
  Job3 --> SBOM[SBOM]
  Job4 --> Sig[cosign sig]
  Job5 --> Registry[OCI registry]
  Cache[actions/cache] -.缓存.-> Job1
  Cache -.缓存.-> Job2
  Runner[runner label / self-hosted] --> Jobs
  OIDC[OIDC token] -.短时凭证.-> Job5

核心关系：event 触发 jobs，jobs 之间用 needs 形成 DAG；cache 跨 run 复用二进制，artifact 跨 job 传递产物；OIDC 提供短期凭证；sign + SBOM 让制品可验证。

9.3 基础知识讲解

9.3.1 论文 / 规范

9.3.2 书

9.3.3 博客 / 文档

9.3.4 人物

9.3.5 方法

9.4 经典问题与经典案例

9.5 学习难点

概念难点

思维难点

工程难点

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

CI 引擎负责 workflow 调度与执行；runner 提供执行环境；artifact / cache 提供跨 job 与跨 run 存储；registry 提供 OCI 制品存储；签名 / SBOM 提供完整性证明。它们之间用 OCI、OIDC、SLSA 互通。

9.6.3 Structure

必须掌握 on event 字段（push / pull_request / workflow_dispatch / schedule）、jobs 结构（runs-on / needs / if / env / permissions / steps）、step 字段（uses / run / with / env / id）、cache key 设计（hashfiles）、artifact retention、OIDC trust policy（sub / aud）、cosign sign / verify-blob。

9.6.4 Ecosystem

GitHub Actions 生态最大；GitLab CI 与 GitLab 平台深度集成；CircleCI 在 monorepo 与 orbs 上有优势。BuildKit 是底层构建引擎，docker buildx 是 CLI。Sigstore 提供 cosign、Rekor、Fulcio。扫描工具还有 Snyk、Grype。

9.6.5 Depth Tiers

本子主题目标是 L3。

9.6.6 Source

• GitHub Actions 文档
• GitHub Actions Security Hardening
• GitLab CI Reference
• BuildKit 文档
• Sigstore cosign
• SLSA v1.0
• 引用版本快照日期：2026-07-30；实作前运行 gh --version、act --version、cosign version。

10. 常见误区

• 缓存 key 用 * 命中率低；
• @main 而不是 @v4 / @sha256:...；
• 默认 permissions: write-all；
• 用 long-lived AWS access key；
• pull_request_target 暴露 secrets 给 fork PR；
• matrix 不限并发，撞 256；
• artifact 存大文件、retention 不调；
• self-hosted runner 当 long-lived 容器用，泄露 secrets；
• OIDC trust policy sub 写得太宽；
• cosign 签了制品但 deploy 不 verify；
• SBOM 输出但没卡 release gate；
• fork PR 跑 workflow 默认 secrets 不可用，写代码时不读文档。

11. 所有知识点分类（统一规则）

1. 编程语言；2. 数据结构与算法；3. 计算机基础；4. 工程技术；5. Web 与后端；6. 前端与客户端；7. 数据与人工智能；8. 项目与职业能力；9. 安全与可靠性。

本计划归属：工程技术 主 + 安全与可靠性 辅。