Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/skills/llms.txt

Use this file to discover all available pages before exploring further.

The gh-fix-ci skill turns a failing CI pipeline into an actionable repair plan. It uses the gh CLI to find failing GitHub Actions checks on the current PR, downloads the relevant run logs, extracts the failure snippet, proposes a concise fix, and waits for your explicit approval before touching any code. External CI providers such as Buildkite are intentionally out of scope — the skill reports their details URL and moves on.

​
Trigger Conditions

Codex activates this skill when you ask it to:
  • Debug or fix failing GitHub Actions checks
  • Investigate why CI is red on a PR
  • Diagnose a broken pipeline and propose a fix
  • Summarize CI log failures on the current branch
This skill applies only to GitHub Actions checks. Checks from external providers (Buildkite, CircleCI, etc.) are flagged with their detailsUrl only — Codex does not attempt to fetch their logs.

​
Prerequisites

Authenticate the GitHub CLI once with repo and workflow scopes before running this skill: 
gh auth login
Verify authentication: 
gh auth status
Both repo and workflow scopes are required so the skill can read check runs and download logs.

​
Workflow

1

Verify gh authentication

The skill runs gh auth status in the repo. If the token is missing or lacks required scopes, Codex pauses and asks you to run gh auth login before proceeding.
2

Resolve the PR

Codex prefers the PR for the current branch:
gh pr view --json number,url
If you supply a PR number or URL explicitly, that takes precedence.
3

Inspect failing checks

The bundled inspect_pr_checks.py script fetches all GitHub Actions check runs, identifies failures, and pulls the relevant log lines:
python "<skill-path>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"
Add --json for machine-readable output, or tune snippet size with --max-lines and --context:
python "<skill-path>/scripts/inspect_pr_checks.py" \
  --repo "." \
  --pr "123" \
  --json

python "<skill-path>/scripts/inspect_pr_checks.py" \
  --repo "." \
  --max-lines 200 \
  --context 40
If the bundled script is unavailable, Codex falls back to manual gh commands:
# List checks
gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow

# Fetch run details and logs
gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha
gh run view <run_id> --log

# Fetch job logs directly if the run is still in progress
gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > logs.txt
4

Scope external checks

Any check whose detailsUrl does not point to a GitHub Actions run is labeled as external. Codex reports the URL and does not fetch logs from that provider.
5

Summarize failures

Codex presents each failing check with its name, run URL, and a concise log snippet highlighting the error. Missing logs are called out explicitly.
6

Propose a fix plan

Codex drafts a focused plan describing what needs to change to make CI green. If the create-plan skill is available, it is used to structure the plan and request your approval. Otherwise, the plan is drafted inline.
7

Implement after approval

Only after you approve the plan does Codex apply changes. It then summarizes the diffs and any test results, and asks whether you want to open or push to the PR.
8

Recheck status

After the fix lands, Codex suggests re-running the relevant tests locally and confirms CI status with:
gh pr checks

​
The inspect_pr_checks.py Script

The bundled script handles common edge cases that raw gh commands miss:

Field drift tolerance

Retries gh pr checks with the available field set when GitHub’s API drops or renames a field.

Job-log fallbacks

Falls back to per-job log fetches when the run-level log is unavailable or still streaming.

Non-zero exit on failure

Exits non-zero when failing checks remain, making it safe to use in automation pipelines.

JSON mode

--json emits structured output for downstream summarization or scripting.

​
Installing

$skill-installer gh-fix-ci
Restart Codex after installation to pick up the new skill.

Build docs developers (and LLMs) love

Get started for freeTalk to us