home / skills / composiohq / awesome-codex-skills / gh-fix-ci

gh-fix-ci skill

safe

This skill analyzes failing GitHub PR checks using gh, summarizes failures, and generates a fix plan with implementation after your approval.

npx playbooks add skill composiohq/awesome-codex-skills --skill gh-fix-ci

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

Files (3)

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, fetches GitHub Actions logs, summarizes the failure context, then drafts a concrete fix plan and implements approved changes. It focuses on GitHub Actions runs; external CI providers are reported but marked out of scope. Authentication via gh with workflow/repo scopes is required before running the skill.

How this skill works

The skill runs a script that locates the PR (current branch or provided PR number/URL), lists checks, and filters for failing GitHub Actions runs. For each failing run it pulls run and job logs, extracts concise failure snippets, and assembles a summary. It then uses a plan workflow to propose changes; after explicit user approval it applies code changes, summarizes diffs and test steps, and suggests rechecking the PR checks.

When to use it

You have a pull request with failing GitHub Actions checks and want an actionable diagnosis.
You need a concise failure snippet and the likely root cause from CI logs.
You want a concrete fix plan drafted and implemented after you approve it.
You need machine-friendly output (JSON) for automation or further processing.
You want to avoid handling non-GitHub CI providers like Buildkite; those should be only reported.

Best practices

Ensure gh is authenticated with workflow and repo scopes (run gh auth login then gh auth status).
Prefer running the bundled inspect_pr_checks.py script which handles field drift and log fallbacks.
If sandboxed, rerun gh auth status with sandbox_permissions=require_escalated to allow network/keyring access.
Do not attempt to modify or debug external CI providers; report their details URL and mark them out of scope.
Require explicit user approval before applying any code changes or opening a PR.

Example use cases

Diagnose a failing unit test that fails only in CI due to missing environment variables and propose a fix to mock or set the env in workflows.
Fetch failing integration test logs, summarize the error stack, propose a targeted code or workflow change, and apply it after approval.
Automate triage for a PR: collect failing job logs, produce a short remediation plan, and implement small fixes (lint, dependency pin, or test adjustment) when approved.
Run as part of a developer workflow: python scripts/inspect_pr_checks.py --repo . --pr 123 --json to feed CI failure details into other automation.

FAQ

What if gh is not authenticated or lacks scopes?

The skill will ask you to run gh auth login and ensure gh auth status shows workflow and repo scopes; in sandboxed environments rerun with sandbox_permissions=require_escalated.

Can this fix external CI providers like Buildkite?

No. External checks are reported with their details URL and explicitly marked out of scope; only GitHub Actions runs are inspected and modified.