github-workflow-auto-fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Workflow Auto-Fix

GitHub工作流自动修复

Automated CI failure analysis and remediation using Claude Code Action.
使用Claude Code Action实现CI失败的自动分析与修复。

When to Use This Skill

适用场景

Use this skill when...Use something else when...
Setting up auto-fix workflow for a repoFixing a single PR's checks (
/git:fix-pr
)
Customizing which workflows trigger auto-fixInspecting workflow runs manually (
/workflow:inspect
)
Understanding the auto-fix patternWriting new workflows from scratch (
/workflow:dev
)
适用本技能的场景...适用其他方案的场景...
为仓库设置自动修复工作流修复单个PR的检查(
/git:fix-pr
自定义触发自动修复的工作流手动检查工作流运行情况(
/workflow:inspect
了解自动修复模式从零开始编写新工作流(
/workflow:dev

Context

上下文信息

  • Workflow exists: !
    find .github/workflows -maxdepth 1 -name 'github-workflow-auto-fix.yml'
  • Current workflows: !
    find .github/workflows -maxdepth 1 -name '*.yml' -type f
  • Claude secrets configured: !
    gh secret list
  • 工作流是否存在:!
    find .github/workflows -maxdepth 1 -name 'github-workflow-auto-fix.yml'
  • 当前工作流:!
    find .github/workflows -maxdepth 1 -name '*.yml' -type f
  • Claude密钥配置情况:!
    gh secret list

Parameters

参数说明

Parse from
$ARGUMENTS
:
  • --setup
    : Create or update the auto-fix workflow in
    .github/workflows/
  • --workflows <names>
    : Comma-separated workflow names to monitor (default: auto-detect CI workflows)
  • --dry-run
    : Show what would be created without writing files
$ARGUMENTS
中解析:
  • --setup
    :在
    .github/workflows/
    目录下创建或更新自动修复工作流
  • --workflows <names>
    :要监控的工作流名称(逗号分隔,默认:自动检测CI工作流)
  • --dry-run
    :显示将要创建的内容但不实际写入文件

Execution

执行步骤

Execute this workflow setup process:
执行以下工作流设置流程:

Step 1: Assess current state

步骤1:评估当前状态

  1. Check if
    .github/workflows/github-workflow-auto-fix.yml
    already exists
  2. List all current workflow files and their
    name:
    fields
  3. Check if
    CLAUDE_CODE_OAUTH_TOKEN
    secret is configured
  1. 检查
    .github/workflows/github-workflow-auto-fix.yml
    是否已存在
  2. 列出所有当前工作流文件及其
    name:
    字段
  3. 检查是否已配置
    CLAUDE_CODE_OAUTH_TOKEN
    密钥

Step 2: Select workflows to monitor

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

If
--workflows
provided, use those. Otherwise, auto-detect suitable workflows:
Good candidates for auto-fix monitoring:
  • CI/test workflows (lint, test, build, type-check)
  • Code quality checks (formatting, style)
  • Config validation workflows
Skip these (not suitable for auto-fix):
  • Release workflows (release-please, deploy)
  • Claude-powered workflows (avoid recursive triggers)
  • Scheduled audit workflows
  • Reusable workflow definitions
如果提供了
--workflows
参数,则使用指定的工作流。否则,自动检测合适的工作流:
适合自动修复监控的工作流:
  • CI/测试工作流(代码检查、测试、构建、类型检查)
  • 代码质量检查(格式化、样式检查)
  • 配置验证工作流
不适合的工作流(跳过):
  • 发布工作流(release-please、部署)
  • 基于Claude的工作流(避免递归触发)
  • 定时审计工作流
  • 可复用工作流定义

Step 3: Generate workflow file

步骤3:生成工作流文件

If
--setup
or workflow is missing, create
.github/workflows/github-workflow-auto-fix.yml
:
yaml
name: Auto-fix Workflow Failures

on:
  workflow_run:
    workflows:
      # List monitored workflows here
      - "CI"
      - "Lint"
    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 *)
如果使用
--setup
参数或工作流文件不存在,则创建
.github/workflows/github-workflow-auto-fix.yml
yaml
name: Auto-fix Workflow Failures

on:
  workflow_run:
    workflows:
      # List monitored workflows here
      - "CI"
      - "Lint"
    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 *)

Step 4: Validate and report

步骤4:验证与报告

  1. Verify the workflow YAML is valid
  2. List the monitored workflows
  3. Check that required secrets exist
  4. Report any missing prerequisites
  1. 验证工作流YAML文件的有效性
  2. 列出被监控的工作流
  3. 检查所需密钥是否存在
  4. 报告任何缺失的前置条件

Architecture

架构流程

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
workflow_run (failure)
        |
        v
  收集日志与上下文信息
        |
        v
  Claude分析失败原因
        |
    +---+---+
    |       |
    v       v
 可修复问题  复杂/外部问题
    |       |
    v       v
 修复并推送  创建Issue
            附带分析结果
    |       |
    v       v
 在PR上评论  在PR上评论
            关联Issue

Safety Guards

安全防护措施

GuardPurpose
actor.type != 'Bot'
Prevent bot-triggered loops
head_branch != 'main'
Never auto-fix main branch directly
Recent fix checkSkip if auto-fix already attempted
Concurrency groupOne auto-fix per branch at a time
max-turns 30
Limit Claude's iteration count
防护措施目的
actor.type != 'Bot'
防止机器人触发的循环
head_branch != 'main'
绝不直接自动修复主分支
近期修复检查如果已尝试过自动修复则跳过
并发组限制每个分支同时仅运行一个自动修复任务
max-turns 30
限制Claude的迭代次数

Prerequisites

前置条件

RequirementHow to set up
CLAUDE_CODE_OAUTH_TOKEN
Repository secret with Claude Code OAuth token
contents: write
permission
Included in workflow permissions
pull-requests: write
permission
Included in workflow permissions
issues: write
permission
For creating issues on complex failures
要求设置方法
CLAUDE_CODE_OAUTH_TOKEN
配置仓库密钥,包含Claude Code OAuth令牌
contents: write
权限
已包含在工作流权限中
pull-requests: write
权限
已包含在工作流权限中
issues: write
权限
用于为复杂失败创建Issue

Agentic Optimizations

智能优化命令

ContextCommand
Check recent failures
gh run list --status failure --json name,headBranch,conclusion -L 10
Get failed logs
gh run view <id> --log-failed | tail -500
Run summary
gh run view <id> --json conclusion,status,jobs
Find associated PR
gh pr list --head <branch> --json number --jq '.[0].number'
List workflow names
grep -h '^name:' .github/workflows/*.yml
场景命令
检查近期失败记录
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