# Ghs Action Fix

> >

- **Type:** Skill
- **Install:** `agentstack add skill-atypical-consulting-githubskills-ghs-action-fix`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Atypical-Consulting](https://agentstack.voostack.com/s/atypical-consulting)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Atypical-Consulting](https://github.com/Atypical-Consulting)
- **Source:** https://github.com/Atypical-Consulting/GitHubSkills/tree/dev/.claude/skills/ghs-action-fix
- **Website:** https://atypical-consulting.github.io/GitHubSkills/

## Install

```sh
agentstack add skill-atypical-consulting-githubskills-ghs-action-fix
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Fix GitHub Actions Pipelines

Detect failing GitHub Actions workflows, diagnose root causes from run logs, apply targeted fixes in worktrees, and create PRs — all in one pass with no prior scan required.

| Do NOT | Do Instead | Why |
|--------|-----------|-----|
| Guess the fix without reading logs | Always run `gh run view --log-failed` first | Wastes time, often makes things worse |
| Replace entire workflow files | Make minimal, targeted changes | Loses complex matrix builds, caching, secrets |
| Fix application code bugs | Report as NEEDS_HUMAN with diagnosis | Out of scope — workflow skill, not app debugger |
| Retry the same fix > 3 times | Circuit breaker: 3 attempts max, then NEEDS_HUMAN | Infinite loop risk |
| Modify files outside `.github/workflows/` | Only touch workflow files | Scope violation — could break the app |
| Skip YAML validation after edits | Always validate YAML before committing | Syntax errors are worse than the original failure |

## Scope Boundary

**Modifies**: `.github/workflows/*.yml` and `.github/workflows/*.yaml` files only.

**Does NOT modify**: Application code, test files, configuration files, dependencies. If CI fails due to broken application code (test failures, compilation errors, missing dependencies), the skill reports NEEDS_HUMAN with a diagnosis of the root cause.

## Context Budget

What to pass to each CI Fix Agent:

| Pass | Do NOT Pass |
|------|-------------|
| Failing workflow file content | All workflow files |
| Failed run ID and log excerpt (first 200 lines) | Full run logs (too large) |
| Repository tech stack summary | Full repo file tree |
| Worktree path and branch name | Other agents' results |
| Workflow file path | Backlog items or scan results |

See `../shared/references/agent-spawning.md` for the full agent spawning protocol.

## Circuit Breaker

| Attempt | Action |
|---------|--------|
| 1st failure | Re-run agent with error context appended to prompt |
| 2nd failure | Re-run with error + stricter constraints |
| 3rd failure | Mark as `NEEDS_HUMAN`, preserve worktree, stop retrying |

After 3 failures on the same workflow, the orchestrator moves on. The worktree is left in place for manual continuation.

References:
- ../shared/references/gh-cli-patterns.md
- ../shared/references/output-conventions.md
- ../shared/references/ui-brand.md
- ../shared/references/argument-parsing.md
- ../shared/references/agent-spawning.md
- ../shared/references/implementation-workflow.md
- ../shared/references/edge-cases.md
- ../shared/references/agent-result-contract.md

Purpose: Direct-action skill for fixing failing GitHub Actions pipelines — no backlog or prior scan needed.

Roles:
1. **Orchestrator** (you) — detects failures, prepares repo, creates worktrees, spawns agents, collects results, cleans up
2. **CI Fix Agents** — one per failing workflow, each diagnosing and fixing in its own worktree

Agent prompt: `agents/ci-fix-agent.md`

### Shared References

| Reference | Path | Use For |
|-----------|------|---------|
| Agent spawning | `../shared/references/agent-spawning.md` | Worktree creation, agent spawning, context budgeting |
| gh CLI patterns | `../shared/references/gh-cli-patterns.md` | Authentication, repo detection, error handling |
| Output conventions | `../shared/references/output-conventions.md` | Status indicators, table formats, summary blocks |
| Implementation workflow | `../shared/references/implementation-workflow.md` | Repo prep, worktree mgmt, branch/commit/push/PR |
| Edge cases | `../shared/references/edge-cases.md` | Rate limiting, content filters, permission errors |
| Agent result contract | `../shared/references/agent-result-contract.md` | Universal agent response format |

The user must have **write access** to the target repository.

Detect, diagnose, and fix failing GitHub Actions workflows, then create PRs.

Outputs:
- PRs created on GitHub for each fixed workflow
- Terminal report with diagnosis summaries and PR links
- NEEDS_HUMAN items listed with root-cause explanations

Next routing:
- Suggest `ghs-merge-prs` to merge the created PRs — "To merge: `/ghs-merge-prs {owner}/{repo}`"
- Suggest `ghs-repo-scan` to run a full health check

Fetch workflow run logs before diagnosis.

## Input

- **Explicit repo**: `ghs-action-fix owner/repo`
- **Implicit repo**: `ghs-action-fix` (detects from `gh repo view`)
- **Specific workflow**: `ghs-action-fix owner/repo --workflow ci.yml`

## Phase 1 — Detect Failing Workflows

```bash
gh run list --repo {owner}/{repo} --limit 30 --json conclusion,workflowName,status,databaseId,headBranch,event 2>&1
```

Group runs by workflow name. For each workflow, find the most recent completed run. Identify workflows where the most recent completed run has `conclusion: "failure"`.

If no failing workflows found:
```
All GitHub Actions workflows are passing. Nothing to fix.
```

## Phase 2 — Prepare Repository

Follow `../shared/references/implementation-workflow.md` §1:
1. Clone or pull the repo into `repos/{owner}_{repo}/`
2. Detect the default branch: `gh repo view {owner}/{repo} --json defaultBranchRef --jq '.defaultBranchRef.name'`
3. Detect tech stack (language, framework, package manager) from repo contents

See `../shared/references/agent-spawning.md` (Repository Cloning section).

## Phase 3 — Confirm with User

Show a triage table of failing workflows:

```
## Failing Workflows: {owner}/{repo}

| # | Workflow | File | Last Run | Branch | Event | Run ID |
|---|----------|------|----------|--------|-------|--------|
| 1 | CI | ci.yml | failure | main | push | 12345 |
| 2 | Deploy | deploy.yml | failure | main | push | 12346 |

Workflows to fix: {N}
Branches to create: fix/action-{slug} per workflow

Proceed with all? (y/n/select)
```

Wait for user confirmation.

## Phase 4 — Create Worktrees

For each confirmed workflow:

**Use absolute paths** — resolve `GHS_ROOT`, `REPO_PATH`, and `WT_DIR` once at skill start (see `agent-spawning.md` § Repository Cloning):

| Step | Command | Notes |
|------|---------|-------|
| 1. Create worktree dir | `mkdir -p "$WT_DIR"` | Sibling to main clone |
| 2. Derive slug | Workflow filename without extension, kebab-case | `ci.yml` → `ci`, `code-quality.yml` → `code-quality` |
| 3. Add worktree | `git -C "$REPO_PATH" worktree add "$WT_DIR/fix--action-{slug}" -b fix/action-{slug}` | One per workflow |
| 4. Verify | `ls "$WT_DIR/fix--action-{slug}/.git"` | Confirm valid |

## Phase 5 — Launch CI Fix Agents

Spawn all agents in a **single Task tool message** for parallel execution.

For each failing workflow, read `agents/ci-fix-agent.md` and substitute:
- `{owner}/{repo}` — repository identifier
- `{default_branch}` — default branch name
- `{worktree_path}` — path to the worktree
- `{branch_name}` — `fix/action-{slug}`
- `{workflow_file}` — workflow filename (e.g., `ci.yml`)
- `{run_id}` — most recent failing run ID
- `{workflow_name}` — human-readable workflow name
- `{tech_stack}` — detected tech stack summary

All agents use `subagent_type: general-purpose`.

## Phase 6 — Collect Results

After all agents complete:

1. Parse each agent's result (JSON per `../shared/references/agent-result-contract.md`)
2. Apply circuit breaker: if an agent returns FAILED, retry up to 2 more times (3 total)
3. After 3 failures, mark as NEEDS_HUMAN

## Phase 7 — Cleanup Worktrees

- **PASS**: Remove worktree (`git worktree remove`) and delete local branch
- **FAILED**: Remove worktree and local branch (fix didn't work anyway)
- **NEEDS_HUMAN**: Leave worktree in place with instructions

Prune: `git -C "$REPO_PATH" worktree prune`

## Phase 8 — Final Report

```
## Results: {owner}/{repo}

| Workflow | File | Diagnosis | Status | PR |
|----------|------|-----------|--------|----|
| CI | ci.yml | Node 16 → 20 upgrade | [PASS] | #42 |
| Deploy | deploy.yml | Broken app test | [NEEDS_HUMAN] | — |

---

Summary:
  Fixed: {n_pass}/{n_total}
  PRs created: {n_prs}

{If any NEEDS_HUMAN items:}
Needs human attention:
  [NEEDS_HUMAN] Deploy (deploy.yml) — CI fails due to broken test in src/auth.test.ts, not a workflow issue
    Worktree: repos/{owner}_{repo}--worktrees/fix--action-deploy/

Next steps:
  To merge PRs: /ghs-merge-prs {owner}/{repo}
  To scan full health: /ghs-repo-scan {owner}/{repo}
```

### Goal-Backward Verification

| Level | Check | Method |
|-------|-------|--------|
| Existence | Output artifact exists | File/PR/API response check |
| Substance | Contains correct content | Diff review, body inspection |
| Wiring | Properly connected | Correct branch target, auto-close refs |

### Cognitive Bias Guards

| Bias | Antidote |
|------|----------|
| First-cause fixation | Read ALL failing steps, not just the first |
| Recency | Check if the workflow worked before the latest commit |
| Tool bias | Don't assume the fix is always a version bump |

## Edge Cases

- **No failing workflows**: Report all green and exit.
- **Only application code failures**: Report NEEDS_HUMAN with root-cause diagnosis for each. Don't modify workflow files if the issue is in app code.
- **Workflow syntax errors**: Fix the YAML syntax. Validate with a YAML parser before committing.
- **Deprecated actions**: Update to latest versions (e.g., `actions/checkout@v2` → `@v4`).
- **Missing secrets**: Report NEEDS_HUMAN — secrets can only be set by the repo admin.
- **Rate limiting**: Back off and retry per `../shared/references/edge-cases.md`.
- **Workflow triggered by schedule/cron**: Include in detection but note that the fix can't be verified by a PR push.
- **Multiple failures in same workflow**: Agent addresses all failures in one fix.
- **Branch already exists**: Check with `git branch -l fix/action-{slug}`. If exists, use `-B` flag or ask user.

## Examples

**Example 1: Single failing workflow**
User says: "fix my CI"
Result: Detects 1 failing workflow (CI, ci.yml), shows triage table, user confirms, creates worktree, agent reads logs (Node 16 EOL), updates `node-version` to 20, creates PR.

**Example 2: Multiple failures**
User says: "fix actions for phmatray/Formidable"
Result: Detects 3 failing workflows, shows triage table, user selects 2, creates 2 worktrees, spawns 2 parallel agents, one fixes deprecated checkout action, other reports NEEDS_HUMAN (broken test), shows results.

**Example 3: All green**
User says: "fix my pipeline"
Result: Checks `gh run list`, all workflows passing. Reports "All GitHub Actions workflows are passing. Nothing to fix."

## Troubleshooting

**"No failing workflows found" but CI badge shows red**
The failing run may be on a non-default branch. Try: `gh run list --repo {owner}/{repo} --branch main --limit 5`

**"Permission denied" when pushing branch**
You need write access. Check: `gh repo view --json viewerPermission`

**Agent can't determine root cause**
If logs are truncated or unclear, the agent marks NEEDS_HUMAN. Check the full logs manually: `gh run view {run_id} --log`

**Worktrees not cleaned up**
Run `git -C "$REPO_PATH" worktree list` and remove stale ones: `git worktree remove `

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Atypical-Consulting](https://github.com/Atypical-Consulting)
- **Source:** [Atypical-Consulting/GitHubSkills](https://github.com/Atypical-Consulting/GitHubSkills)
- **License:** MIT
- **Homepage:** https://atypical-consulting.github.io/GitHubSkills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-atypical-consulting-githubskills-ghs-action-fix
- Seller: https://agentstack.voostack.com/s/atypical-consulting
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.