home / skills / davila7 / claude-code-templates / gh-fix-ci

gh-fix-ci skill

safe

/cli-tool/components/skills/development/gh-fix-ci

This skill inspects failing PR checks with gh, summarizes failure context, and drafts an approval-ready fix plan for implementing changes.

This is most likely a fork of the gh-fix-ci skill from composiohq

npx playbooks add skill davila7/claude-code-templates --skill gh-fix-ci

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.8 KB

---
name: gh-fix-ci
description: Inspect GitHub PR checks with gh, pull failing GitHub Actions logs, summarize failure context, then create a fix plan and implement after user approval. Use when a user asks to debug or fix failing PR CI/CD checks on GitHub Actions and wants a plan + code changes; for external checks (e.g., Buildkite), only report the details URL and mark them out of scope.
metadata:
  short-description: Fix failing Github CI actions
---

# Gh Pr Checks Plan Fix

## Overview

Use gh to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure snippet, then propose a fix plan and implement after explicit approval.
- Depends on the `plan` skill for drafting and approving the fix plan.

Prereq: ensure `gh` is authenticated (for example, run `gh auth login` once), then run `gh auth status` with escalated permissions (include workflow/repo scopes) so `gh` commands succeed. If sandboxing blocks `gh auth status`, rerun it with `sandbox_permissions=require_escalated`.

## Inputs

- `repo`: path inside the repo (default `.`)
- `pr`: PR number or URL (optional; defaults to current branch PR)
- `gh` authentication for the repo host

## Quick start

- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
- Add `--json` if you want machine-friendly output for summarization.

## Workflow

1. Verify gh authentication.
   - Run `gh auth status` in the repo with escalated scopes (workflow/repo) after running `gh auth login`.
   - If sandboxed auth status fails, rerun the command with `sandbox_permissions=require_escalated` to allow network/keyring access.
   - If unauthenticated, ask the user to log in before proceeding.
2. Resolve the PR.
   - Prefer the current branch PR: `gh pr view --json number,url`.
   - If the user provides a PR number or URL, use that directly.
3. Inspect failing checks (GitHub Actions only).
   - Preferred: run the bundled script (handles gh field drift and job-log fallbacks):
     - `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
     - Add `--json` for machine-friendly output.
   - Manual fallback:
     - `gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow`
       - If a field is rejected, rerun with the available fields reported by `gh`.
     - For each failing check, extract the run id from `detailsUrl` and run:
       - `gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha`
       - `gh run view <run_id> --log`
     - If the run log says it is still in progress, fetch job logs directly:
       - `gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > "<path>"`
4. Scope non-GitHub Actions checks.
   - If `detailsUrl` is not a GitHub Actions run, label it as external and only report the URL.
   - Do not attempt Buildkite or other providers; keep the workflow lean.
5. Summarize failures for the user.
   - Provide the failing check name, run URL (if any), and a concise log snippet.
   - Call out missing logs explicitly.
6. Create a plan.
   - Use the `plan` skill to draft a concise plan and request approval.
7. Implement after approval.
   - Apply the approved plan, summarize diffs/tests, and ask about opening a PR.
8. Recheck status.
   - After changes, suggest re-running the relevant tests and `gh pr checks` to confirm.

## Bundled Resources

### scripts/inspect_pr_checks.py

Fetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet. Exits non-zero when failures remain so it can be used in automation.

Usage examples:
- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"`
- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "https://github.com/org/repo/pull/123" --json`
- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --max-lines 200 --context 40`

Overview

This skill inspects failing GitHub PR checks using the gh CLI, pulls actionable GitHub Actions logs, summarizes failure context, and drafts a fix plan. After you approve the plan, it implements the changes and suggests rechecks to confirm resolution. External CI providers are detected and reported as out of scope.

How this skill works

It uses gh to locate the PR and enumerate checks, then fetches Actions run and job logs to extract concise failure snippets. The skill marks non-GitHub Actions checks as external and reports their details URL only. It drafts a repair plan (via an integrated planning step), requests your approval, then applies approved fixes and summarizes diffs and test results.

When to use it

A PR has failing GitHub Actions checks and you want a diagnosis plus a repair plan.
You need concise failure snippets and run URLs to triage flaky or cryptic CI errors.
You want the tool to implement approved code or config fixes and open or propose a follow-up PR.
You need automation-friendly output (JSON) to feed into other tools or CI workflows.

Best practices

Ensure gh is authenticated with required workflow/repo scopes before running the skill.
Run the inspection from the repository root or provide the repo path to avoid ambiguous results.
Use the --json option for machine-readable summaries when integrating into automation.
Confirm approval explicitly before any automated code changes are applied.
If checks reference an external provider (e.g., Buildkite), copy the details URL and investigate that provider separately.

Example use cases

A unit test fails in a PR; fetch failing job logs, summarize the stack trace, and propose a targeted code fix.
A workflow step times out repeatedly; identify the failing step, propose a resource or timeout adjustment, and implement the change after approval.
A lint job fails due to a changed rule; show the log snippet, draft a rule tweak or code modification plan, and apply the approved change.
A flaky test intermittently fails; capture logs, suggest retries or isolation strategies, and create a fix branch if approved.
A CI config syntax error prevents job start; extract the error lines from runner logs, propose a config correction, and commit the fix on approval.

FAQ

What authentication does this skill require?

gh must be authenticated with workflow/repo scopes. Run gh auth login and verify with gh auth status before inspecting checks.

Can the skill fix failures from external CI providers?

No. External checks are marked out of scope; the skill reports the details URL so you can inspect them in the provider's UI.