github-workflow-auto-fix
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGitHub 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 ( |
| Customizing which workflows trigger auto-fix | Inspecting workflow runs manually ( |
| Understanding the auto-fix pattern | Writing new workflows from scratch ( |
| 适用本技能的场景... | 适用其他方案的场景... |
|---|---|
| 为仓库设置自动修复工作流 | 修复单个PR的检查( |
| 自定义触发自动修复的工作流 | 手动检查工作流运行情况( |
| 了解自动修复模式 | 从零开始编写新工作流( |
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- : Create or update the auto-fix workflow in
--setup.github/workflows/ - : Comma-separated workflow names to monitor (default: auto-detect CI workflows)
--workflows <names> - : Show what would be created without writing files
--dry-run
从中解析:
$ARGUMENTS- :在
--setup目录下创建或更新自动修复工作流.github/workflows/ - :要监控的工作流名称(逗号分隔,默认:自动检测CI工作流)
--workflows <names> - :显示将要创建的内容但不实际写入文件
--dry-run
Execution
执行步骤
Execute this workflow setup process:
执行以下工作流设置流程:
Step 1: Assess current state
步骤1:评估当前状态
- Check if already exists
.github/workflows/github-workflow-auto-fix.yml - List all current workflow files and their fields
name: - Check if secret is configured
CLAUDE_CODE_OAUTH_TOKEN
- 检查是否已存在
.github/workflows/github-workflow-auto-fix.yml - 列出所有当前工作流文件及其字段
name: - 检查是否已配置密钥
CLAUDE_CODE_OAUTH_TOKEN
Step 2: Select workflows to monitor
步骤2:选择要监控的工作流
If provided, use those. Otherwise, auto-detect suitable workflows:
--workflowsGood 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 or workflow is missing, create :
--setup.github/workflows/github-workflow-auto-fix.ymlyaml
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.ymlyaml
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 issueworkflow_run (failure)
|
v
收集日志与上下文信息
|
v
Claude分析失败原因
|
+---+---+
| |
v v
可修复问题 复杂/外部问题
| |
v v
修复并推送 创建Issue
附带分析结果
| |
v v
在PR上评论 在PR上评论
关联IssueSafety Guards
安全防护措施
| Guard | Purpose |
|---|---|
| Prevent bot-triggered loops |
| 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 |
| Limit Claude's iteration count |
| 防护措施 | 目的 |
|---|---|
| 防止机器人触发的循环 |
| 绝不直接自动修复主分支 |
| 近期修复检查 | 如果已尝试过自动修复则跳过 |
| 并发组限制 | 每个分支同时仅运行一个自动修复任务 |
| 限制Claude的迭代次数 |
Prerequisites
前置条件
| Requirement | How to set up |
|---|---|
| Repository secret with Claude Code OAuth token |
| Included in workflow permissions |
| Included in workflow permissions |
| For creating issues on complex failures |
| 要求 | 设置方法 |
|---|---|
| 配置仓库密钥,包含Claude Code OAuth令牌 |
| 已包含在工作流权限中 |
| 已包含在工作流权限中 |
| 用于为复杂失败创建Issue |
Agentic Optimizations
智能优化命令
| Context | Command |
|---|---|
| Check recent failures | |
| Get failed logs | |
| Run summary | |
| Find associated PR | |
| List workflow names | |
| 场景 | 命令 |
|---|---|
| 检查近期失败记录 | |
| 获取失败日志 | |
| 运行摘要 | |
| 查找关联PR | |
| 列出工作流名称 | |