When a pull request turns red, gh-fix-ci connects the check status to the failing run and relevant code. Its scope is GitHub Actions. It identifies a meaningful failure before proposing a fix; an external CI service generally stays a details link rather than being treated as logs the Skill has already inspected.
Install and prepare
This guide covers the standalone Skill retained in openai/skills. That repository is deprecated and current examples have moved to openai/plugins; the instructions here describe the linked standalone version, not the latest plugin.
Enter this line in the Codex conversation, not a terminal. If the installed Skill does not appear, restart Codex.
$skill-installer gh-fix-ci
- A checkout of the target repository and an accurate PR link
- Authenticated GitHub CLI with access to checks and run logs
- An environment able to run the relevant project checks
Check the account with gh auth status, then use gh pr checks for the current branch or provide a PR number or URL. A pending check is not yet a failed check. [4]
Try a first task
In the target repository, start by limiting the investigation to the current PR:
$gh-fix-ci
Investigate the current branch PR’s failed GitHub Actions checks. First show the failing job, a relevant log excerpt, related code and a minimal repair plan. Wait for my confirmation before editing. Distinguish code errors, missing environment setup and external CI. Do not delete tests or bypass checks to make the status green.
Work through the task
-
Locate the failed run. Verify the PR and commit, then inspect the failed check’s details and logs. Do not explain the latest code using a failure from an older commit.
-
Define a focused repair. Separate the first meaningful error from downstream failures and choose a small change with a concrete validation step.
-
Implement and recheck. After the plan is confirmed, run relevant local checks and inspect the remote results for the corresponding commit. State what could not be verified.
Go from a failing check to a testable repair
Fix the PR number and failing commit SHA first, then inspect that commit’s checks. gh pr checks <PR-number> helps locate the failed item; a GitHub Actions workflow with several jobs still requires the relevant job log. Separate the first meaningful failing command from its downstream errors. If dependency installation fails, later tests may never have run; they are not independent defects just because the workflow is red.
The proposed repair should answer four questions: did the failure occur during install, build, test or deploy; is it a code regression or environment mismatch; which files need the smallest change; and what equivalent local check can run. If a third-party provider owns the failure and its log is unavailable through Actions, retain the details link and an open question instead of inventing a diagnosis.
Why a local pass is not the end
After the patch, run the relevant command and compare the lockfile, runtime version, working directory and required environment variables with CI. The remote check must belong to the new commit containing the fix. A green run on an old commit or a local pass does not establish that the updated PR passed. If the new run is queued, mark it pending and report the logs actually seen and the remaining verification gap.
Another case: failure on only one runtime version
Suppose Node 20 passes but Node 18 fails in a PR test matrix. Ask: “Confirm both jobs ran against the same commit. Compare the failed command, dependency installation and error stack, then assess whether the runtime difference explains it. If evidence is insufficient, list the next logs to inspect before editing.” The installed Skill bundles scripts/inspect_pr_checks.py. python "<skill-directory>/scripts/inspect_pr_checks.py" --repo "." --pr "123" --json gives a machine-readable summary; replace the directory and PR number. Acceptance requires the specific failed job and log evidence, not merely “CI is red.”
Check the result
A useful result names the failed check, its cause, the change and the checks that actually passed. Mark unfinished remote runs as pending. Passing local tests is useful evidence, but it is not the same as a successful remote workflow.
Common blockers
Logs are unavailable. Check permissions and supply an accessible run or saved log. Keep the diagnosis conditional when the failure cannot be inspected.
It passes locally but fails in CI. Compare lockfiles, runtime versions, environment variables and working directories before reproducing the same conditions.
The failure belongs to an external service. Hand its details URL to the appropriate workflow instead of claiming an Actions repair covered it.
Move from a failed check to the relevant log
First ask for the failed check name, run ID, and nearby error lines before reading an entire log. The helper can extract failure context; if logs are still pending, retry later or inspect the specific job. When a check’s detailsUrl points to Buildkite, Jenkins, or another external provider, follow that provider’s original log rather than assuming the GitHub Actions path applies.