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 repo	Fixing a single PR's checks ( `/git:fix-pr` )
Customizing which workflows trigger auto-fix	Inspecting workflow runs manually ( `/workflow:inspect` )
Understanding the auto-fix pattern	Writing 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：评估当前状态

Check if

.github/workflows/github-workflow-auto-fix.yml

already exists

List all current workflow files and their
```
name:
```
fields
Check if
```
CLAUDE_CODE_OAUTH_TOKEN
```
secret is configured

检查

.github/workflows/github-workflow-auto-fix.yml

是否已存在

列出所有当前工作流文件及其
```
name:
```
字段
检查是否已配置
```
CLAUDE_CODE_OAUTH_TOKEN
```
密钥

Step 2: Select workflows to monitor

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

--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：生成工作流文件

--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：验证与报告

Verify the workflow YAML is valid
List the monitored workflows
Check that required secrets exist
Report any missing prerequisites

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

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

安全防护措施

Guard	Purpose
`actor.type != 'Bot'`	Prevent bot-triggered loops
`head_branch != 'main'`	Never auto-fix main branch directly
Recent fix check	Skip if auto-fix already attempted
Concurrency group	One 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

前置条件

Requirement	How 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

智能优化命令

Context	Command
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`