GitHub Actions 工作流

GHA 主流程（skill-flow-block）

  [ 事件：push / PR / schedule / workflow_dispatch / 调用方 workflow_call ]
                    │
                    ▼
         [ 解析：workflow 文件匹配分支 / 路径 / activity types ]
                    │
                    ▼
    [ 并发：concurrency 组取消或排队；避免与部署 job 竞态 ]
                    │
                    ▼
         [ Job：runs-on、permissions 降级、environment 与必要 secrets ]
                    │
           ┌────────┴────────┐
           ▼                 ▼
  [ 内联 steps：uses pin（SHA）+ 显式 with ]     [ 复用：workflow_call / composite / 可重用 job 模板 ]
           │                 │
           └────────┬────────┘
                    ▼
         [ 产出：artifact、摘要、状态检查；失败时保留日志与复现命令 ]

可复用工作流对照矩阵

下表对比常见「复用」形态：点击行可在下方查看 SKILL 中建议写明的要点（仅本地高亮，无网络请求）。

当前选中：点击表格中的一行以查看建议写入 SKILL 的侧重点。

触发器、concurrency 与路径过滤

• on：为 PR 与 push 分别写清 paths/paths-ignore；workflow_dispatch 的 inputs 要有类型、默认值与说明。
• concurrency：组名包含环境或分支占位，避免不同 PR 互相取消；部署类 job 慎用 cancel-in-progress。
• 复用入口：被 workflow_call 调用的 workflow 应校验 inputs 枚举，拒绝空字符串或危险默认分支名。

完整的可复用 workflow（reusable workflow with inputs/outputs）示例：

# .github/workflows/reusable-build.yml  — 可复用 workflow
name: Reusable Build

on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.js 版本'
        type: string
        default: '20'
        required: false
      environment:
        description: '部署目标环境'
        type: string
        required: true
    secrets:
      REGISTRY_TOKEN:
        required: true
    outputs:
      image-tag:
        description: '构建产物镜像 tag'
        value: ${{ jobs.build.outputs.tag }}

jobs:
  build:
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    outputs:
      tag: ${{ steps.tag.outputs.tag }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'

      - name: Restore build cache
        uses: actions/cache@v4
        with:
          path: |
            .next/cache
            node_modules/.cache
          key: build-${{ runner.os }}-${{ inputs.node-version }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            build-${{ runner.os }}-${{ inputs.node-version }}-
            build-${{ runner.os }}-

      - run: npm ci --prefer-offline
      - run: npm run build

      - id: tag
        run: |
          echo "tag=$(node -p "require('./package.json').version")-${{ github.sha }}" >> "$GITHUB_OUTPUT"

# ---- 调用方 workflow ----
# .github/workflows/deploy.yml
# jobs:
#   build:
#     uses: ./.github/workflows/reusable-build.yml
#     with:
#       node-version: '20'
#       environment: staging
#     secrets:
#       REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

矩阵测试配置：多版本 × 多平台并行测试：

# 矩阵测试：Node 18/20/22 × ubuntu/windows
jobs:
  test:
    strategy:
      fail-fast: false      # 一个组合失败不停止其他
      matrix:
        node: ['18', '20', '22']
        os: [ubuntu-24.04, windows-latest]
        exclude:
          - node: '18'
            os: windows-latest   # 排除特定组合
    runs-on: ${{ matrix.os }}
    name: Test Node ${{ matrix.node }} on ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

permissions、OIDC 与 action pin

• 最小权限：顶层 permissions 先收紧，再在 job 级按需放宽；需要写内容库时显式 contents: write 并说明理由。
• OIDC：云角色信任策略绑定 sub/aud；避免把环境名或可伪造 claim 单独作为唯一条件。
• Pin：优先完整 commit SHA；标签需配合组织级允许列表或 dependabot 更新策略。

Secrets 安全传递：environments + required reviewers 手动审批配置：

# 最小权限顶层收紧 + 各 job 按需放宽 + environment 手动审批
permissions: {}   # 顶层全部关闭

jobs:
  test:
    runs-on: ubuntu-24.04
    permissions:
      contents: read    # 仅读源码
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  deploy-prod:
    runs-on: ubuntu-24.04
    needs: test
    # environment 绑定保护规则：在仓库 Settings > Environments 配置
    # Required reviewers: 至少 1 人审批后 job 才能继续运行
    environment:
      name: production
      url: https://myapp.example.com
    permissions:
      id-token: write   # OIDC token
      contents: read
    steps:
      - uses: actions/checkout@v4

      # Pin action 到完整 commit SHA，而非 @v4 标签
      - uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

      - run: |
          # Secrets 通过 environment 隔离，此处 ${{ secrets.DB_PASSWORD }}
          # 仅在 production environment 的 job 中可见
          aws ssm put-parameter \
            --name "/myapp/prod/db-password" \
            --value "${{ secrets.DB_PASSWORD }}" \
            --type SecureString --overwrite

缓存、容器与环境保护

• 缓存：键包含 lockfile 哈希与 runner OS；restore-keys 仅作降级，文档中写明可接受的「部分命中」行为。
• 容器 job：镜像 digest、非 root、与供应链技能一致的 SBOM/扫描门禁。
• Environment：保护规则、required reviewers 与 secrets 分环境；生产部署 workflow 与仅 CI 的 workflow 分离。

缓存优化：actions/cache 的正确键设计与多层 restore-keys：

# npm 依赖缓存：精确键 + 两级降级
- name: Cache npm dependencies
  uses: actions/cache@v4
  id: npm-cache
  with:
    path: ~/.npm
    # 精确键：OS + node版本 + lockfile哈希
    key: npm-${{ runner.os }}-node20-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-node20-
      npm-${{ runner.os }}-
  # cache-hit: true 时跳过 npm install

- run: npm ci --prefer-offline
  # --prefer-offline: 优先使用 ~/.npm 缓存，降低网络依赖

# Docker layer 缓存（BuildKit）
- name: Build with layer cache
  uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    cache-from: type=gha,scope=myapp-build
    cache-to: type=gha,mode=max,scope=myapp-build
    tags: myapp:${{ github.sha }}

# Terraform provider 缓存
- name: Cache Terraform providers
  uses: actions/cache@v4
  with:
    path: ~/.terraform.d/plugin-cache
    key: tf-${{ runner.os }}-${{ hashFiles('**/.terraform.lock.hcl') }}
    restore-keys: |
      tf-${{ runner.os }}-