A red GitHub Actions job is a symptom. The useful question is which step failed and what that step expected. Rewriting the whole workflow usually wastes time.
1. Open the first failing step
Expand the job log and find the earliest step with a non-zero exit. Note the runner OS, the branch or tag, and whether the failure is new after a dependency or secrets change.
2. Check prerequisites before the build
Confirm checkout succeeded, required secrets and variables exist for that environment, and the working directory is correct. Many “build” failures are missing tokens, wrong paths, or a matrix cell that never had those secrets.
3. Reproduce locally when you can
Run the same commands from the failing step in a clean environment close to the runner. If it passes locally and fails in CI, compare Node/Java versions, caches, permissions and network access to private registries.
4. Fix the smallest cause
Adjust one thing: a version pin, a cache key, a permission, or a test that only fails under CI timing. Re-run the same workflow and confirm both this job and related jobs still pass.
Keep secrets out of chat. Describe which secret name is missing or invalid without pasting values. Rotate anything that may have been exposed.
What to bring to a support session
The workflow file path, the failing step name, a redacted log excerpt, and the change that preceded the failure.
Official references
Published 3 November 2026. Check changes against your own environment and your team’s process.