How to Debug Failing GitHub Actions in Codex: Complete Guide to Automated CI Debugging

The gh-fix-ci skill enables Codex to automatically identify failing GitHub Actions checks, extract and summarize logs, and generate an actionable fix plan that requires your explicit approval before any code changes occur.

Debugging CI failures manually involves tedious log diving and context switching. The gh-fix-ci skill from the ComposioHQ/awesome-codex-skills repository eliminates this friction by orchestrating the GitHub CLI (gh) to inspect pull request checks, fetch failure logs, and propose fixes. This guide explains exactly how to debug failing GitHub Actions in Codex using the skill’s Python scripts and approval-based workflow.

Prerequisites: Configure the GitHub CLI

Codex relies on the official GitHub CLI as its only external dependency. Before invoking the skill, ensure gh is authenticated with sufficient scopes.

Run the following to authenticate:

gh auth login

# Select GitHub.com and grant `repo` + `workflow` scopes when prompted

Verify authentication status:

gh auth status

If you are operating in a sandboxed environment that blocks elevated permissions, escalate using:

gh auth status --sandbox-permissions=require_escalated

How the gh-fix-ci Skill Works

The skill combines a high-level workflow definition with a low-level Python helper to interact with the GitHub API. The architecture consists of four key components:

• SKILL.md located at gh-fix-ci/SKILL.md defines the orchestration logic, inputs, and the eight-step workflow (lines 30‑60) that Codex follows.
• inspect_pr_checks.py at gh-fix-ci/scripts/inspect_pr_checks.py is the bundled script that drives gh commands, extracts failing check IDs, and handles log retrieval fallbacks.
• plan skill (dependency) provides the "plan-then-execute" safety layer, ensuring Codex generates a fix plan for user approval before modifying any code.
• GitHub CLI (gh) performs authentication, PR resolution, and Actions run inspection.

Step-by-Step: Debug Failing GitHub Actions in Codex

Follow this sequence to diagnose and resolve CI failures automatically.

1. Resolve the Target PR

The script accepts either a specific PR number/URL or auto-detects the PR associated with your current branch using gh pr view.

2. Execute the Inspection Script

Run the core script to analyze failing checks:

python "<path-to-skill>/scripts/inspect_pr_checks.py" \
  --repo "." \
  --pr "<PR-number-or-URL>" \
  --max-lines 200 \
  --context 40

Optional flags:

• Add --json to receive a machine-readable JSON payload for downstream automation.
• Adjust --max-lines and --context to control the log extraction volume (defaults are 200 lines and 40-line context).

3. Review the Failure Summary

The script outputs a concise summary including the check name, URL, and a trimmed log snippet:

❌ Test suite failed – https://github.com/.../actions/runs/123456789
── snippet ──
AssertionError: expected 42 but got 0

4. Approve the Generated Fix Plan

After summarizing the failure, Codex invokes the plan skill. This step analyzes the log snippet and proposes concrete fixes (for example, updating test expectations or adding missing environment variables). Review the plan and confirm with yes or request modifications.

5. Apply the Fix

Once approved, Codex executes the plan—editing files, running tests, and committing changes. It displays a diff and asks whether to open a new pull request.

6. Verify the Resolution

After pushing changes, re-check the PR status:

gh pr checks <pr-number>

Confirm that previously failing checks now report SUCCESS. If failures persist, repeat the workflow.

Deep Dive: Log Extraction and Fallback Logic

The inspect_pr_checks.py script employs a resilient two-tier approach to retrieve logs when standard fields are missing or runs are incomplete.

First, it attempts to view the run log directly:

# Retrieve the failing run ID from the check's detailsUrl

run_id = details_url.split('/')[-1]

# Try the high-level log command first

log = subprocess.run(
    ["gh", "run", "view", run_id, "--log"],
    capture_output=True,
    text=True,
).stdout

If the high-level command returns empty (due to field drift or incomplete runs), it falls back to the GitHub API:

# Fallback: download the raw job log via the API if the above returns empty

if not log:
    job_id = extract_job_id(run_id)  # helper that parses the run JSON

    log = subprocess.run(
        [
            "gh", "api",
            f"/repos/{owner}/{repo}/actions/jobs/{job_id}/logs"
        ],
        capture_output=True,
        text=True,
    ).stdout

This fallback mechanism ensures Codex can debug failures even when the GitHub UI omits standard log links.

Safety Features: Plan Before You Execute

The gh-fix-ci skill never modifies code without explicit consent. It delegates all fix generation to the plan skill, which creates a structured proposal describing exactly what files will change and why. You must approve this plan before Codex writes any disk changes, enforcing a safe "plan-then-execute" pattern.

Summary

The gh-fix-ci skill provides a complete, reproducible pipeline for debugging GitHub Actions failures in Codex:

• Authentication validation up-front ensures gh has repo and workflow scopes.
• PR resolution works with explicit references or auto-detects the current branch’s PR.
• Robust log extraction in inspect_pr_checks.py handles missing fields via API fallbacks.
• Concise summaries translate opaque CI output into actionable failure descriptions.
• Mandatory approval via the plan skill prevents unauthorized code changes.

By invoking this skill as shown above, you convert manual log-diving into an automated, approval-gated debugging workflow.

Frequently Asked Questions

What permissions does the GitHub CLI need for Codex to debug Actions?

The GitHub CLI requires repo and workflow scopes. These allow Codex to read private repository data and inspect workflow runs. Run gh auth login and explicitly grant these scopes when prompted.

How does Codex handle missing or incomplete GitHub Actions logs?

When gh run view returns empty output (often due to in-progress runs or UI field drift), the inspect_pr_checks.py script automatically falls back to the GitHub API endpoint /repos/{owner}/{repo}/actions/jobs/{job_id}/logs using gh api. This ensures log retrieval succeeds even when standard CLI commands fail.

Can Codex automatically push fixes without asking me?

No. The gh-fix-ci skill integrates with the plan skill to enforce a strict approval step. After summarizing the failure, Codex generates a fix plan describing all proposed changes. It only modifies code after you explicitly confirm the plan with yes.

What if I don't know the specific PR number?

You do not need to know it. If you omit the --pr argument, the script uses gh pr view to automatically detect the PR associated with your current branch. Alternatively, you can pass a full PR URL instead of a number.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}