Diagnose failed Netlify deploys and file them in Linear

Watch my Netlify account for failed deploys using a Netlify poll trigger on the deploy_failed event. Every time a deploy fails, run the diagnosis below and leave a record of it in Linear. Production failures should also reach a human by email. Preview and branch failures should stay quiet.

Start by calling Netlify Get Deploy for the deploy that just failed and read the full record: the site name, the deploy context (production, deploy preview, or branch deploy), the branch, the failing commit reference, the deploy state, and any error message and build summary fields. There is no operation for fetching raw build logs, so treat the error message and summary on the deploy record as the only error detail available. Quote from those fields rather than inventing log output.

Then call Netlify List Site Deploys for the same site to build context. Find the most recent successful deploy, and note when it ran and which commit it was on. Scan the recent failed deploys for that site and decide whether this is a brand new regression, meaning the previous deploy in the same context succeeded, or a repeat of a failure we have already seen, meaning one or more recent deploys failed with a similar error.

Classify the likely root cause as exactly one of: a missing or misconfigured environment variable, a dependency install failure, a build command error, a build timeout, or a broken redirect configuration. If the evidence does not clearly support one of those, say the cause is unclear and describe what you did see instead of forcing a category. Base the classification on the actual error text, and write a short suggested fix that names the specific variable, package, command, or redirect rule whenever the error mentions one.

Before filing anything, call Linear Search Issues to look for an open issue that already covers this same recurring failure, searching on the site name plus the distinctive part of the error. If you find one that clearly matches, call Linear Add Comment to Issue and record the new occurrence: when the deploy failed, the failing commit, the current error excerpt, and how many times this failure has now been seen. Do not open a second issue in that case.

If no matching open issue exists, call Linear Create Issue in the engineering team I specify. Title it with the site name and the classified cause. In the description include the site name, the deploy context and branch, the failing commit, a short verbatim excerpt of the error message, the classified root cause, your suggested fix, and a link to the deploy in Netlify. Also note the last successful deploy and its commit, so whoever picks the issue up can see what changed in between.

Only when the failed deploy is a production deploy, send an email using Gmail Send a Message to the on-call engineer address configured for this workflow. Keep the body to two lines: the first naming which site failed and the classified cause, the second giving the suggested fix. Include a link to the failed deploy and a link to the Linear issue you just created or commented on. If the deploy context is a deploy preview or a branch deploy, stop after the Linear step and send no email at all.