<p>A failed CI log can contain hundreds of follow-on errors. I begin with the failing command and the first error that explains why the command stopped. ChatGPT can help summarize a pasted, sanitized excerpt. Codex can inspect the repository and run the matching command when it has authorized access.</p><p>I do not paste a complete log until I remove secrets, private package URLs, account identifiers, and customer data. The smallest useful excerpt often contains the command, runtime version, stack trace, and nearby setup lines.</p>

<h2>Capture the exact failure</h2>

<p>I record the workflow name, job, commit, command, exit code, and first useful error. Later errors may be symptoms of a missing generated file or failed install. I keep enough lines above the error to see environment setup.</p><p>I ask the assistant to distinguish facts in the log from hypotheses. A confident cause without a matching line or repository path stays unverified.</p>

<h2>Compare local and CI assumptions</h2>

<p>I compare Node and package-manager versions, lockfile use, environment variables, operating system, working directory, caches, and generated artifacts. The local command may pass because an ignored file exists or a developer shell exports a value.</p><p>I reproduce with the CI command in a clean environment where practical. Changing several dependencies before reproducing destroys evidence.</p>

<h2>Inspect the smallest relevant files</h2>

<p>Codex can trace the failing script into its configuration and imports. I limit the initial read to the workflow file, package script, failing module, and nearby test. This reduces speculation across unrelated code.</p><p>If the error concerns a missing secret, I verify the key name and job scope without revealing the value. If it concerns permissions, I inspect the required action before expanding a role.</p>

<h2>Make one testable change</h2>

<p>I choose the narrowest change that explains the failure: pin the supported runtime, generate the expected artifact, correct the path, or fix the type error. I add a regression test when the failure came from application behavior.</p><p>I avoid "cleanup" in the same patch. A small diff makes it clear whether the original cause was correct.</p>

<h2>Rerun the same command</h2>

<p>The original failing command must pass with the same relevant environment. I then run the surrounding project checks because a narrow fix can break another package or platform. CI receives the committed change and produces the final evidence.</p><p>I do not declare success from a local substitute if the failure happened only in the hosted runner.</p>

<h2>Write the incident note</h2>

<p>I record the first error, cause, fix, validation, and prevention. Repeated environment drift may justify a pinned toolchain or preflight script.</p><ul><li>Logs are sanitized.</li><li>The first causal error is identified.</li><li>Local and CI versions are compared.</li><li>One narrow fix is tested.</li><li>The hosted job passes on the target commit.</li></ul>

<h2>Need a safer development workflow?</h2>

<p>Terry Hunt Dev helps teams diagnose builds and deployment pipelines through <a href="/services/devops-consulting">DevOps consulting</a>. Send the sanitized command and first error through the <a href="/contact">contact page</a>, not the full private log.</p>

Use AI-assisted CI debugging to isolate the first useful error, compare local and CI assumptions, inspect relevant files, and prove the fix safely.

Debugging a Failed CI Build with ChatGPT and Codex

Find the first useful CI error, compare environments, test the smallest cause, and prove the fix with the original command.

CI Resources & Benchmarks

Debugging a Failed CI Build with ChatGPT and Codex

Need hands-on help with CI?