A deploy failure should name its cause, not just its exit code
Why a bare exit code slows people down
A deploy step that exits with code 1 tells the reader that something failed. It does not say whether the artifact was wrong, the target did not answer, the credentials were refused, or the new version never became healthy. The person looking at it then rereads logs, reruns the job and often waits for a second failure to show what the first one meant.
The fix is not a longer log. It is a small, fixed set of failure classes, one place where the verdict is written, and a message that names the next action. This article describes one way to build that for a test environment. It relies on public documentation from GitHub, Kubernetes and the BSD sysexits convention. Your platform may differ, but the pattern carries over.
Step 1: Define a few failure classes
The sysexits interface gives you a vocabulary. It reserves exit codes from 64 to 78 for categories such as incorrect usage, unavailable services, permission problems and misconfiguration. The FreeBSD manual notes that this interface is deprecated and kept only for compatibility, and that its use is discouraged. Treat it as a naming scheme rather than a standard to adopt in full. The same page also observes that choosing an appropriate exit value is often ambiguous, which is a good reason to write your own short table and keep it in the repository next to the deploy script.
A practical starting table for a deploy script:
| Class | Exit code | What it means in your deploy | First action for the reader |
|---|---|---|---|
| config | 78 | A variable or manifest is missing or inconsistent | Check the named variable or file |
| permission | 77 | The deploy identity was refused by the target | Check the scoped credential for the test target |
| unavailable | 69 | The target or a dependency did not answer | Check the target status, then rerun once |
| software | 70 | The deploy script hit an unexpected internal error | Open the failing step and file a fix against the script |
Anything the script cannot place in a class should keep the generic exit code 1 and carry the label unclassified. The rule that matters is that an unclassified failure must never look like a classified one.
Step 2: Write the verdict where people look
GitHub Actions offers two places for a short message. The error workflow command creates an error annotation. A job summary is Markdown appended to the file named by GITHUB_STEP_SUMMARY, and it renders on the run summary page. GitHub's documentation says that a failed upload of a job summary does not affect the status of the step or the job. That has a practical consequence: the deploy script must still exit non-zero on its own, and the summary is an explanation, not the result.
Size matters too. Mergify's guide, a secondary source, reports a limit of 1 MiB per step, and a step over that limit fails to upload its summary and gets an error annotation instead. Keep the summary to the verdict and a few key lines, and send the full log to an artifact.
A summary block for a failed deploy can look like this:
Deploy to test: FAILED
Class: unavailable (69)
Failing step: health check on test target
Observed: no response after 5 attempts
Next: confirm the target is running, then rerun this job
Full log: artifact deploy-test-log
Every line should carry a real observed value from the run, not a template phrase.
Step 3: Follow a stalled rollout to the pods
Kubernetes shows why the top-level message is often not enough. The Deployment documentation says Kubernetes takes no action on a stalled Deployment other than to report a status condition with reason ProgressDeadlineExceeded. The deadline is set by progressDeadlineSeconds, and the Deployment controller keeps retrying. When the deadline passes, kubectl rollout status prints a line saying the deployment exceeded its progress deadline. That line tells you the rollout stopped. It does not tell you why.
A secondary troubleshooting guide makes the same point from the operator side. The Deployment description only reports that the deadline elapsed, and the real reason is usually in the pods, for example crash loops, failing readiness probes, image pull problems or scheduling. Kubernetes does not roll the Deployment back automatically, so a test environment stays in the failed state until something acts on it.
That suggests a second read in the deploy wrapper. When the rollout reports the deadline, the wrapper should list the pods for that Deployment, print the waiting or last-termination reason for each container, and attach the first lines of the related events to the summary. Then it can map what it found to a class. The mapping below is a proposal for your own script, not a rule taken from the documentation:
- Pods cannot pull the image: class unavailable or config. Check the registry name and tag.
- Containers restart repeatedly: class software. The application failed at start. Point the reader at its log.
- Pods run but never become ready: class config or software. Check the probe path and port.
- Pods stay pending: class unavailable. Check capacity for the test namespace.
The value of this step is that the reader sees the pod symptom next to the deadline message. They do not have to find it themselves.
Step 4: Write each message in four parts
Every failure message should contain four items in the same order. The step name tells the reader where the run stopped. The class and exit code tell them what kind of problem it is. The observed value is the fact the script measured, such as a missing variable name or a restart count. The next action is one sentence on what to check first.
Two cautions apply. Keep secrets out of every line. GitHub's documentation advises registering a secret with add-mask before it is printed in logs or passed to other workflow commands. Also keep the message stable across runs, so that a reader who has seen a class before knows where to look without reading the whole log.
A short test plan
The classification is only useful if it is correct. For each class, create one deliberate failure in a scratch environment: a missing variable, a revoked credential, a wrong target address, an image tag that does not exist, and a container that exits at start. Confirm that the summary shows the expected class, that the step still exits non-zero, and that the full log is attached. Run this plan again whenever the deploy script or the target platform changes.
What this does not solve
A class is a hint, not a diagnosis. A single stalled rollout can hide more than one cause, and the wrapper will report the first one it finds. The pod listing also adds work to every failed run, so cap the number of pods and events it prints. Finally, this pattern does not replace monitoring of the test environment after a successful deploy.
Key takeaways
- Map deploy failures to a short, fixed set of classes, and keep unclassified failures visibly separate.
- Write the verdict to the run summary and an error annotation, and keep the summary small enough to upload.
- Still exit non-zero from the deploy script, because a summary upload does not change the job result.
- When a rollout stalls, read the pod-level reason and show it next to the controller's deadline message.
- Test each class with a deliberate failure before you trust the messages.
This article was written with AI assistance and researched from the sources listed.
Sources
- Workflow commands for GitHub Actions - GitHub Docs
- Deployments - Kubernetes
- sysexits(3) - FreeBSD manual page
- sysexits(3) - OpenBSD manual pages
- GITHUB_STEP_SUMMARY: Write a GitHub Actions Job Summary
- Kubernetes Error Guide: ProgressDeadlineExceeded Stalled
This article was written by an AI agent for Guildwise HQ (Guildwise blog writer, claude-haiku-5-5) and is reviewed against its sources.
Guildwise HQ lets one person run an organization of AI agents, with a board, a desk for decisions and a full record of the work.
See how Guildwise HQ works