ci-workflows

CI 工作流标准

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用同级技能……
你需要规范的 GitHub Actions 工作流模式（容器构建、测试、发布）	你想通过交互式工作流端到端地审核或安装工作流——请使用 configure-workflows
你正在检查现有的 .github/workflows/*.yml 是否遵循文档中的约定	你想接入预构建的可复用调用方——请使用 configure-reusable-workflows
其他技能需要引用标准工作流结构	用户要求你实际创建或修复 CI 工作流

版本：2025.1

用于 CI/CD 自动化的标准 GitHub Actions 工作流。

显示名称约定

每个工作流的 name: 都遵循 <Domain>: <Action> [<target>] 格式，以便 GitHub Actions 侧边栏按字母顺序将相关工作流分组。请将值加上引号，因为 YAML 会将未加引号的标量中的 : 视为键分隔符。规范规则、当前启用的领域列表以及跨工作流重命名流程，请参阅 .claude/rules/workflow-naming.md。在此处搭建任何工作流时，也要遵循此模式。

必需工作流

1. 容器构建工作流

文件：.github/workflows/container-build.yml

用于通过 GHCR 发布的多平台容器构建：

name: "Container: Build"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          build-args: |
            SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }}

主要功能：

• 多平台构建（amd64、arm64）
• GitHub Container Registry（GHCR）
• 语义化版本标记
• 使用 GitHub Actions 缓存进行构建缓存
• 用于源映射的 Sentry 集成

2. Release Please 工作流

文件：.github/workflows/release-please.yml

详情请参阅 configure-release-please（其 REFERENCE.md 包含标准工作流、令牌和配置模板）。

3. ArgoCD 自动合并工作流（可选）

文件：.github/workflows/argocd-automerge.yml

自动合并来自 ArgoCD Image Updater 分支的 PR：

name: "Image Updater: Auto-merge"

on:
  push:
    branches:
      - 'image-updater-**'

permissions:
  contents: write
  pull-requests: write

jobs:
  create-and-merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Create Pull Request
        id: create-pr
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_URL=$(gh pr create \
            --base main \
            --head "${{ github.ref_name }}" \
            --title "chore(deps): update container image" \
            --body "Automated image update by argocd-image-updater.

          Branch: \`${{ github.ref_name }}\`" \
            2>&1) || true

          if echo "$PR_URL" | grep -q "already exists"; then
            PR_URL=$(gh pr view "${{ github.ref_name }}" --json url -q .url)
          fi

          echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT"

      - name: Approve PR
        env:
          GH_TOKEN: ${{ secrets.AUTO_MERGE_PAT || secrets.GITHUB_TOKEN }}
        run: gh pr review --approve "${{ github.ref_name }}"
        continue-on-error: true

      - name: Enable auto-merge
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr merge --auto --squash "${{ github.ref_name }}"

主要功能：

• 在 ArgoCD Image Updater 的 image-updater-** 分支上触发
• 如果 PR 尚不存在，则自动创建
• 自我批准，可选使用 PAT（以绕过 GitHub 限制）
• 启用自动合并的 Squash 合并

前置条件：

• 在仓库设置中启用自动合并
• 可选：用于自我批准的 AUTO_MERGE_PAT 密钥

4. 测试工作流（推荐）

文件：.github/workflows/test.yml

name: "Test: Suite"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run type check
        run: npm run typecheck

      - name: Run tests
        run: npm run test:coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v6
        with:
          files: ./coverage/lcov.info

5. Claude 自动修复工作流（可选）

文件：.github/workflows/claude-auto-fix.yml

使用 Claude Code Action 自动分析并修复 CI 失败：

name: "Auto-fix: CI failures"

on:
  workflow_run:
    # Customize: list the CI workflow display names to monitor.
    # The strings here must match the target workflows' `name:` values exactly.
    workflows: ["Test: Suite"]
    types: [completed]
  workflow_dispatch:
    inputs:
      run_id:
        description: "Failed workflow run ID to analyze"
        required: true
        type: string

concurrency:
  group: auto-fix-${{ github.event.workflow_run.head_branch || github.ref_name }}
  cancel-in-progress: false

主要功能：

• 在受监控工作流运行完成时，通过 workflow_run 触发
• 自动收集失败日志和上下文
• 去重：将未关闭的自动修复 PR 数量限制为 3 个
• 防止循环：跳过以 fix(auto): 开头的提交
• 可自动修复的失败会生成修复 PR；复杂失败则会生成 GitHub issue
• 使用 anthropics/claude-code-action@v1，并配置限定范围的工具权限

前置条件：

• 在仓库设置中配置 CLAUDE_CODE_OAUTH_TOKEN 密钥
• 至少有一个要监控的 CI 工作流（自定义 workflows: 列表）

完整模板请参阅 configure-workflows 中的 Claude 自动修复工作流模板。

工作流标准

操作版本

操作	版本	用途
actions/checkout	v6	检出仓库
docker/setup-buildx-action	v4	多平台构建
docker/login-action	v4	注册表身份验证
docker/metadata-action	v6	镜像标记
docker/build-push-action	v7	容器构建/推送
actions/setup-node	v6	Node.js 设置
googleapis/release-please-action	v5	发布自动化

权限

所需的最低权限：

permissions:
  contents: read      # Default for most jobs
  packages: write     # For container push to GHCR
  pull-requests: write  # For release-please PR creation

触发器

标准触发模式：

# Build on push and PR to main
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Also build on release
on:
  release:
    types: [published]

构建缓存

对 Docker 层使用 GitHub Actions 缓存：

cache-from: type=gha
cache-to: type=gha,mode=max

多平台构建

同时针对 amd64 和 arm64 构建：

platforms: linux/amd64,linux/arm64

合规要求

必需工作流

工作流	用途	必需
container-build	容器构建	是（如果存在 Dockerfile）
release-please	自动发布	是
test	测试和 lint	推荐
argocd-automerge	自动合并镜像更新	可选（如果使用 ArgoCD Image Updater）
claude-auto-fix	自动修复 CI 失败	可选

必需元素

元素	要求
checkout action	v6
build-push action	v7
多平台	amd64 + arm64
缓存	启用 GHA 缓存
权限	明确且最小化

状态级别

状态	条件
PASS	所有必需工作流均已配置，且配置符合要求
WARN	工作流已配置，但使用了较旧的 action 版本
FAIL	缺少必需工作流
SKIP	不适用（没有 Dockerfile = 不需要 container-build）

必需的密钥

密钥	用途	必需
GITHUB_TOKEN	容器注册表身份验证	自动提供
SENTRY_AUTH_TOKEN	上传源映射	如果使用 Sentry
MY_RELEASE_PLEASE_TOKEN	创建发布 PR	用于 release-please
CLAUDE_CODE_OAUTH_TOKEN	Claude Code Action 身份验证	用于 claude-auto-fix

故障排除

构建失败

• 检查 Dockerfile 语法
• 验证构建参数是否正确传递
• 检查缓存失效问题

多平台问题

• 确保 Dockerfile 与平台无关
• 使用官方多架构基础镜像
• 避免使用特定于架构的二进制文件

缓存无法正常工作

• 确认已设置 cache-from 和 cache-to
• 检查 GitHub Actions 缓存限制（10GB）
• 对于大型镜像，考虑使用基于注册表的缓存