# How to Debug Failing GitHub Actions in Codex: Complete Guide to Automated CI Debugging > Debug failing GitHub Actions in Codex with gh-fix-ci. Automatically identify issues, summarize logs, and get an actionable fix plan for faster CI debugging. Approve changes before they're made. - Repository: [Composio/awesome-codex-skills](https://github.com/composiohq/awesome-codex-skills) - Tags: how-to-guide - Published: 2026-04-26 --- **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: ```bash gh auth login # Select GitHub.com and grant `repo` + `workflow` scopes when prompted ``` Verify authentication status: ```bash gh auth status ``` If you are operating in a sandboxed environment that blocks elevated permissions, escalate using: ```bash 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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/SKILL.md)** located at [`gh-fix-ci/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/inspect_pr_checks.py)** at [`gh-fix-ci/scripts/inspect_pr_checks.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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: ```bash python "/scripts/inspect_pr_checks.py" \ --repo "." \ --pr "" \ --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: ```bash gh pr checks ``` 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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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: ```python # 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: ```python # 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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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.