github-workflow-auto-fix

# GitHub Workflow Auto-Fix Automated CI failure analysis and remediation using Claude Code Action. Two shapes, selected by flag: | Shape | Flag | Output | Use for | |-------|------|--------|---------| | **Single-repo inline** (default) | `--setup` | One self-contained `github-workflow-auto-fix.yml` | A single repo that owns its auto-fix logic | | **Reusable `workflow_call`** | `--reusable` (+ `--caller`) | A `reusable-ci-autofix.yml` definition plus a thin `auto-fix.yml` caller | Multiple repos invoking one shared template | ## When to Use This Skill | Use this skill when... | Use something else when... | |------------------------|---------------------------| | Setting up auto-fix for a single repo (default) | Fixing a single PR's checks (`/git:fix-pr`) | | Setting up a reusable template multiple repos invoke (`--reusable`) | Inspecting workflow runs manually (`/workflow:inspect`) | | Customizing which workflows trigger auto-fix | Writing new workflows from scratch (`/workflow:dev`) | ## Context - Inline workflow exists: !`find . -path '*/.github/workflows/*' -maxdepth 3 -name 'github-workflow-auto-fix.yml'` - Reusable workflow exists: !`find . -path '*/.github/workflows/*' -maxdepth 3 -name 'reusable-ci-autofix.yml' -type f` - Caller workflow exists: !`find . -path '*/.github/workflows/*' -maxdepth 3 -name 'auto-fix.yml' -type f` - Current workflows: !`find . -path '*/.github/workflows/*' -maxdepth 3 -name '*.yml' -type f` - Claude secrets configured: !`gh secret list` ## Parameters Parse from `$ARGUMENTS`: - `--setup`: Create or update the single-repo inline workflow in `.github/workflows/github-workflow-auto-fix.yml` - `--reusable`: Create or update the reusable `workflow_call` definition in `.github/workflows/reusable-ci-autofix.yml` (see Step 5) - `--caller`: Create the thin caller workflow in `.github/workflows/auto-fix.yml` that invokes the reusable definition (see Step 5) - `--workflows <names>`: Comma-separated workflow names to monitor (default: auto-detect CI workflows) - `--dry-run`: Show what would be created without writing files Default (no `--reusable`/`--caller`) generates the single-repo inline workflow described in Steps 1–4. `--reusable`/`--caller` switch to the reusable variant in Step 5. ## Execution Execute this workflow setup process: ### Step 1: Assess current state 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 ### Step 2: Select workflows to monitor 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 ### Step 3: Generate workflow file If `--setup` or workflow is missing, create `.github/workflows/github-workflow-auto-fix.yml`. The workflow's display name follows `<Domain>: <Action>` (`Auto-fix:` is the canonical domain for `workflow_run`-triggered remediation; quote the value because YAML treats `:` as a key separator). The strings under `workflows:` must match the **display names** of the target workflows exactly — update both sides whenever a target's `name:` changes. See `.claude/rules/workflow-naming.md`. ```yaml 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 }} # One flag per line: scripts/check-workflow-model.sh matches # `--model`/`--effort` anchored at line start in a folded scalar. # The tool boundary belongs in `--allowedTools` here — `additional_permissions` # takes a GitHub permissions MAP, so a tool list passed there is inert. claude_args: >- --model opus --effort medium --max-turns 30 --allowedTools "Read,Write,Edit,Grep,Glob,Bash(git *),Bash(gh *)" prompt: | <analysis-and-fix-prompt> additional_permissions: | actions: read ``` ### Step 4: Validate and report 1. Verify the workflow YAML is valid 2. List the monitored workflows 3. Check that required secrets exist 4. Report any missing prerequisites ### Step 5: Reusable variant (`--reusable` / `--caller`) When `--reusable` or `--caller` is passed, generate the `workflow_call` shape instead of the single-repo inline workflow. The full templates live in [REFERENCE.md](REFERENCE.md). 1. **`--reusable`** — create `.github/workflows/reusable-ci-autofix.yml` from [REFERENCE.md](REFERENCE.md) § Reusable Workflow. Customize: - `auto_fixable_criteria` / `not_auto_fixable_criteria` defaults to match the project's tech stack - `verification_commands` default to match the project's linter/formatter commands - `max_turns` (default: 50) 2. **`--caller`** — create `.github/workflows/auto-fix.yml` from [REFERENCE.md](REFERENCE.md) § Caller Workflow. Customize: - The monitored workflow `name:` strings in the `workflows:` list (display names — must match each target's `name:` exactly) - `auto_fixable_criteria` / `verification_commands` overrides for the project's tools 3. **Display-name convention** — the caller's `name:` follows `<Domain>: <Action>` (`Auto-fix: CI failures` is canonical; the reusable definition itself uses `Reusable: CI auto-fix`). Quote values containing colons. See `.claude/rules/workflow-naming.md`. 4. Validate both YAML files, list the monitored workflows, and confirm `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` exists. The reusable variant adds dedup (max 2 open auto-fix PRs), `workflow_dispatch` with a `pr_number` input, and fan-out — see the Architecture and Safety Guards below, and REFERENCE.md for the rationale. ## Architecture Single-repo inline (default): ``` 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 ``` The reusable variant wraps the same analyze→fix/issue core in a `workflow_call` definition fronted by a thin caller (`workflow_run` + `workflow_dispatch` with fan-out and a dedup gate). See [REFERENCE.md](REFERENCE.md) § Reusable Workflow and § Cross-Repository Usage for the full templates. ## Safety Guards | Guard | Variant | Purpose | |-------|---------|---------| | `actor.type != 'Bot'` | both | Prevent bot-triggered loops | | `head_branch != 'main'` | both | Never auto-fix main branch directly | | Recent fix check / `!startsWith(commit, 'fix(auto):')` | both | Skip if auto-fix already attempted; prevent recursive loops | | Concurrency group per branch | both | One auto-fix per branch at a time | | `max-turns` limit | both | Limit Claude's iteration count (inline 30, reusable 50 default) | | Max 2 open auto-fix PRs | reusable | Prevent PR flooding across repos | | `timeout-minutes: 30` | reusable | Prevent runaway jobs | ## 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 | ## 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` |