Debug and fix failing GitHub Actions CI/CD pipelines

GitHub Actions Pipeline Debugger connects a failed workflow log to the job, step, YAML definition, and underlying script responsible for the failure. It proposes a direct diff that addresses the observed cause. The diagnostic scope includes missing secrets, dependency and runtime mismatches, runner environment problems, shell syntax, deprecated actions, caching, flaky tests, and timeout limits.

The workflow binds its analysis to a particular execution. Record the repository, run ID, attempt, event, head SHA, runner, and failing step. Read the workflow and referenced scripts at that same commit. This prevents a fix from being based on a newer version of main that differs from the failed run. Source defects, permissions problems, missing tools, and observation timeouts remain separate explanations.

Use this skill when a failed GitHub Actions run produces a long or misleading log, when a test passes locally but fails in CI, or when an action needs a supported runtime. It can also identify slow workflow steps. Local-versus-CI investigation covers timezone, headless browser state, memory limits, and races caused by parallel execution.

A retry requires judgment. Temporary registry or network failures can resemble structural configuration defects, while deployment and publication steps may repeat side effects. A passing rerun does not resolve a deterministic defect. Required checks and tests must retain their intended strength.

For shell syntax faults, inspect the run: block at the failed commit.

Supply the failure log together with the relevant workflow definition. Before sharing logs, redact credentials, tokens, private keys, private URLs, deployment targets, and internal paths. The skill cannot securely inspect repository secret values; it can infer missing or malformed authentication only from the supplied evidence.

The output is a proposed YAML or script diff. For example, a deployment step that lacks its expected environment variable can use the following supplied pattern:

       - name: Deploy App
         run: npm run deploy
+        env:
+          DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}

A proposal is not execution evidence. Validation requires pushing the change and triggering a workflow run. Bash changes should use dry-run flags or staging execution where possible.

Investigation centers on GitHub Actions workflow files under .github/workflows/*.yml and the scripts they reference. Review permissions: when a job writes to repositories, packages, or deployment environments. Authentication belongs in GitHub Secrets rather than hardcoded YAML.

Action upgrades require checking upstream support and installed runner compatibility, then pinning the reviewed full commit SHA. The historical checkout v2-to-v4 example illustrates runtime migration; it is not a recommendation to select v4 as the current release. For dependency installation failures, bypassing actions caching can help determine whether an outdated cache key preserved corrupt dependencies.