github-workflow-auto-fix

GitHub 工作流自动修复

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

何时使用此技能

在以下情况使用此技能……	在以下情况使用其他方法……
为仓库设置自动修复工作流	修复单个 PR 的检查（/git:fix-pr）
自定义触发自动修复的工作流	手动检查工作流运行（/workflow:inspect）
了解自动修复模式	从头编写新工作流（/workflow:dev）

上下文

• 工作流是否存在：!find .github/workflows -maxdepth 1 -name 'github-workflow-auto-fix.yml'
• 当前工作流：!find .github/workflows -maxdepth 1 -name '*.yml' -type f
• Claude 密钥是否已配置：!gh secret list

参数

从 $ARGUMENTS 解析：

• --setup：在 .github/workflows/ 中创建或更新自动修复工作流
• --workflows <names>：要监控的工作流名称，以逗号分隔（默认：自动检测 CI 工作流）
• --dry-run：显示将要创建的内容，但不写入文件

执行

执行此工作流设置流程：

步骤 1：评估当前状态

1. 检查 .github/workflows/github-workflow-auto-fix.yml 是否已存在
2. 列出所有当前工作流文件及其 name: 字段
3. 检查是否已配置 CLAUDE_CODE_OAUTH_TOKEN 密钥

步骤 2：选择要监控的工作流

如果提供了 --workflows，则使用指定的工作流。否则，自动检测适合的工作流：

适合自动修复监控的工作流：

• CI／测试工作流（lint、test、build、type-check）
• 代码质量检查（格式、风格）
• 配置验证工作流

跳过这些工作流（不适合自动修复）：

• 发布工作流（release-please、deploy）
• Claude 驱动的工作流（避免递归触发）
• 定期运行的审计工作流
• 可复用工作流定义

步骤 3：生成工作流文件

如果指定了 --setup 或工作流文件不存在，则创建 .github/workflows/github-workflow-auto-fix.yml。

工作流的显示名称遵循 <Domain>: <Action> 格式（Auto-fix: 是由 workflow_run 触发的修复操作所采用的标准域；请将此值加上引号，因为 YAML 会将 : 视为键分隔符）。workflows: 下的字符串必须与目标工作流的显示名称完全一致——每当目标工作流的 name: 发生变化时，都要更新两处。请参阅 .claude/rules/workflow-naming.md。

name: "Auto-fix: CI failures"

on:
  workflow_run:
    workflows:
      # List monitored workflows by display name (must match their `name:` exactly)
      - "Test: Suite"
      - "Plugin: Lint skills"
    types: [completed]

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

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read
  id-token: write

jobs:
  auto-fix:
    if: >-
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.actor.type != 'Bot' &&
      github.event.workflow_run.head_branch != 'main' &&
      github.event.workflow_run.head_branch != 'master'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout failed branch
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}
          fetch-depth: 0

      - name: Gather failure context
        id: context
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          RUN_ID="${{ github.event.workflow_run.id }}"
          gh run view "$RUN_ID" --log-failed 2>&1 | tail -500 > .auto-fix-failed-logs.txt
          gh run view "$RUN_ID" --json conclusion,status,name,headBranch,headSha,jobs > .auto-fix-run-summary.json
          PR_NUMBER=$(gh pr list --head "${{ github.event.workflow_run.head_branch }}" --json number --jq '.[0].number' 2>/dev/null || echo "")
          echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
          echo "run_id=$RUN_ID" >> "$GITHUB_OUTPUT"
          RECENT_FIX=$(git log --oneline -5 --format='%s' | grep -c 'fix:.*resolve CI failure' || true)
          echo "recent_fix_count=$RECENT_FIX" >> "$GITHUB_OUTPUT"

      - name: Skip if already attempted
        if: steps.context.outputs.recent_fix_count != '0'
        run: echo "::notice::Skipping - recent auto-fix commit exists"

      - name: Analyze and fix with Claude
        if: steps.context.outputs.recent_fix_count == '0'
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          direct_prompt: |
            <analysis-and-fix-prompt>
          additional_permissions: |
            Read
            Write
            Edit
            Grep
            Glob
            Bash(git *)
            Bash(gh *)

步骤 4：验证并报告

1. 验证工作流 YAML 是否有效
2. 列出监控的工作流
3. 检查所需密钥是否存在
4. 报告任何缺失的前置条件

架构

workflow_run (failure)
        |
        v
  Gather logs & context
        |
        v
  Claude analyzes failure
        |
    +---+---+
    |       |
    v       v
  Fixable  Complex/External
    |       |
    v       v
  Fix &    Open issue
  push     with analysis
    |       |
    v       v
  Comment  Comment on PR
  on PR    linking issue

安全防护

防护措施	用途
actor.type != 'Bot'	防止由机器人触发的循环
head_branch != 'main'	绝不直接自动修复 main 分支
检查近期修复记录	若已尝试自动修复，则跳过
并发组	同一分支一次只执行一个自动修复
max-turns 30	限制 Claude 的迭代次数

前置条件

要求	设置方法
CLAUDE_CODE_OAUTH_TOKEN	包含 Claude Code OAuth 令牌的仓库密钥
contents: write 权限	已包含在工作流权限中
pull-requests: write 权限	已包含在工作流权限中
issues: write 权限	用于在遇到复杂失败时创建议题

Agent 式优化

上下文	命令
检查近期失败	gh run list --status failure --json name,headBranch,conclusion -L 10
获取失败日志	gh run view <id> --log-failed | tail -500
运行摘要	gh run view <id> --json conclusion,status,jobs
查找关联的 PR	gh pr list --head <branch> --json number --jq '.[0].number'
列出工作流名称	grep -h '^name:' .github/workflows/*.yml