building-ci-pipelines

构建 CI 流水线

目的

CI/CD 流水线可自动化软件测试、构建和部署。本技能提供一系列模式，帮助你在 GitHub Actions、GitLab CI、Argo Workflows 和 Jenkins 中构建稳健、安全且高效的流水线。重点领域：供应链安全（SLSA）、单体仓库优化、缓存和并行化。

何时使用此技能

在以下情况下调用：

• 为新项目设置持续集成
• 实施自动化测试工作流
• 构建带有安全溯源信息的容器镜像
• 优化缓慢的 CI 流水线（尤其是单体仓库）
• 实施 SLSA 供应链安全
• 配置多平台构建
• 设置 GitOps 自动化
• 从旧版 CI 系统迁移

平台选择

托管于 GitHub → GitHub Actions（原生支持 SLSA、提供 10K+ 个操作、支持 OIDC） 托管于 GitLab → GitLab CI（父子流水线、内置安全功能） Kubernetes → Argo Workflows（基于 DAG、事件驱动） 旧版系统 → Jenkins（尽可能迁移）

平台比较

功能	GitHub Actions	GitLab CI	Argo	Jenkins
易用性	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐
SLSA	原生支持	手动	良好	手动
单体仓库	良好	优秀	手动	插件

快速入门模式

模式 1：基础 CI（Lint → Test → Build）

# GitHub Actions
name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint

  test:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

模式 2：矩阵策略（多平台）

test:
  runs-on: ${{ matrix.os }}
  strategy:
    matrix:
      os: [ubuntu-latest, windows-latest, macos-latest]
      node-version: [18, 20, 22]
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm test

并行运行 9 个作业（3 个操作系统 × 3 个版本）：耗时 5 分钟，而顺序运行需 45 分钟。

模式 3：单体仓库变更检测（Turborepo）

build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # Required for affected detection

    - uses: actions/setup-node@v4
      with:
        node-version: 20

    - name: Build affected
      run: npx turbo run build --filter='...[origin/main]'
      env:
        TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
        TURBO_TEAM: ${{ vars.TURBO_TEAM }}

单体仓库的 CI 耗时可缩短 60-80%。

模式 4：SLSA Level 3 溯源信息

name: SLSA Build
on:
  push:
    tags: ['v*']

permissions:
  id-token: write
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - uses: actions/checkout@v4
      - name: Build container
        id: build
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

  provenance:
    needs: build
    permissions:
      id-token: write
      actions: read
      packages: write
    uses: slsa-framework/slsa-github-generator/.github/workflows/[email protected]
    with:
      image: ghcr.io/${{ github.repository }}
      digest: ${{ needs.build.outputs.digest }}
      registry-username: ${{ github.actor }}
    secrets:
      registry-password: ${{ secrets.GITHUB_TOKEN }}

验证：

cosign verify-attestation --type slsaprovenance \
  --certificate-identity-regexp "^https://github.com/slsa-framework" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/myorg/myapp@sha256:abcd...

模式 5：OIDC 联合（无需凭据）

deploy:
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read
  steps:
    - uses: actions/checkout@v4

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
        aws-region: us-east-1

    - name: Deploy
      run: aws s3 sync ./dist s3://my-bucket

优势：无需存储凭据、有效期为 1 小时、提供完整审计跟踪。

模式 6：安全扫描

security:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Gitleaks (secret detection)
      uses: gitleaks/gitleaks-action@v2

    - name: Snyk (vulnerability scan)
      uses: snyk/actions/node@master
      env:
        SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

    - name: SBOM generation
      uses: anchore/sbom-action@v0
      with:
        format: spdx-json
        output-file: sbom.spdx.json

缓存

自动依赖缓存

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'  # Auto-caches ~/.npm
- run: npm ci

支持：npm、yarn、pnpm、pip、poetry、cargo、go

手动控制缓存

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/bin
      ~/.cargo/registry
      target/
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      ${{ runner.os }}-cargo-

多层缓存（Nx）

- name: Nx Cloud (build outputs)
  run: npx nx affected -t build
  env:
    NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

- name: Vite Cache
  uses: actions/cache@v4
  with:
    path: '**/node_modules/.vite'
    key: vite-${{ hashFiles('package-lock.json') }}

- name: TypeScript Cache
  uses: actions/cache@v4
  with:
    path: '**/tsconfig.tsbuildinfo'
    key: tsc-${{ hashFiles('tsconfig.json') }}

结果：构建耗时缩短 70-90%。

并行化

作业级并行化

jobs:
  unit-tests:
    steps:
      - run: npm run test:unit

  integration-tests:
    steps:
      - run: npm run test:integration

  e2e-tests:
    steps:
      - run: npm run test:e2e

三个作业会同时运行。

测试分片

test:
  strategy:
    matrix:
      shard: [1, 2, 3, 4]
  steps:
    - run: npm test -- --shard=${{ matrix.shard }}/4

20 分钟的测试套件 → 5 分钟（提速 4 倍）。

语言示例

Python

test:
  strategy:
    matrix:
      python-version: ['3.10', '3.11', '3.12']
  steps:
    - uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - run: pipx install poetry
    - run: poetry install
    - run: poetry run ruff check .
    - run: poetry run mypy .
    - run: poetry run pytest --cov

Rust

test:
  strategy:
    matrix:
      os: [ubuntu-latest, windows-latest, macos-latest]
      rust: [stable, nightly]
  steps:
    - uses: dtolnay/rust-toolchain@master
      with:
        toolchain: ${{ matrix.rust }}
        components: rustfmt, clippy
    - uses: Swatinem/rust-cache@v2
    - run: cargo fmt -- --check
    - run: cargo clippy -- -D warnings
    - run: cargo test

Go

test:
  steps:
    - uses: actions/setup-go@v5
      with:
        go-version: '1.23'
        cache: true
    - run: go mod verify
    - uses: golangci/golangci-lint-action@v4
    - run: go test -v -race -coverprofile=coverage.txt ./...

TypeScript

test:
  strategy:
    matrix:
      node-version: [18, 20, 22]
  steps:
    - uses: pnpm/action-setup@v3
      with:
        version: 8
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile
    - run: pnpm run lint
    - run: pnpm run type-check
    - run: pnpm test

最佳实践

安全性

应该：

• 使用 OIDC，而非长期有效的凭据
• 将操作固定到提交 SHA：actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
• 限制权限：permissions: { contents: read }
• 在每次提交时扫描密钥（Gitleaks）
• 为发布版本生成 SLSA 溯源信息

不应该：

• 在日志中暴露密钥
• 未经验证就使用 pull_request_target
• 信任未经验证的第三方操作

性能

应该：

• 在单体仓库中使用变更检测
• 缓存依赖项和构建产物
• 并行运行彼此独立的作业
• 快速失败：strategy.fail-fast: true
• 使用远程缓存（Turborepo/Nx Cloud）

不应该：

• 每次提交都重新构建所有内容
• 在 PR 检查中运行耗时很长的测试
• 使用通用缓存键

调试

# Enable debug logging
env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

# SSH into runner
- uses: mxschmitt/action-tmate@v3

高级模式

详细指南请参阅以下参考资料：

• github-actions-patterns.md - 可复用工作流、复合操作、矩阵策略、OIDC 设置
• gitlab-ci-patterns.md - 父子流水线、动态生成、运行器配置
• argo-workflows-guide.md - DAG 模板、产物传递、事件驱动触发器
• slsa-security-framework.md - SLSA Levels 1-4、溯源信息生成、cosign 验证
• monorepo-ci-strategies.md - Turborepo/Nx/Bazel 变更检测算法
• caching-strategies.md - 多层缓存、Docker 优化、缓存失效
• parallelization-patterns.md - 测试分片、作业依赖、DAG 设计
• secrets-management.md - 用于 AWS/GCP/Azure 的 OIDC、Vault 集成、密钥轮换

示例

可运行的完整工作流：

• examples/github-actions-basic/ - 入门模板（lint/test/build）
• examples/github-actions-monorepo/ - 使用远程缓存的 Turborepo
• examples/github-actions-slsa/ - SLSA 级别 3 来源证明
• examples/gitlab-ci-monorepo/ - 父子动态流水线
• examples/argo-workflows-dag/ - 菱形 DAG 并行化
• examples/multi-language-matrix/ - 跨平台测试

实用脚本

无令牌执行：

• scripts/validate_workflow.py - 验证 YAML 语法和最佳实践
• scripts/generate_github_workflow.py - 根据模板生成工作流
• scripts/analyze_ci_performance.py - CI 指标分析
• scripts/setup_oidc_aws.py - 自动配置 AWS OIDC

相关技能

testing-strategies - 测试执行策略（单元测试、集成测试、端到端测试） deploying-applications - 部署自动化与 GitOps auth-security - 密钥管理与身份验证 observability - 流水线监控与告警