Diagnose failed Netlify deploys and file them in Linear
When a Netlify deploy fails, an agent works out the likely cause, opens or updates a Linear ticket, and emails on-call only when your live site is affected.
Netlify
Linear
GmailEngineeringNotifications & AlertsEmail AutomationWatch 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.
What does this prompt do?
- Watches your Netlify sites and reacts the moment a deploy fails, instead of leaving you to spot it later.
- Reads the failed deploy and compares it against your recent deploy history to tell a brand new breakage apart from one you have seen before.
- Sorts the likely cause into plain categories such as a missing setting, a package install problem, a build command error, a timeout, or a bad redirect rule.
- Opens a Linear ticket with the site, the commit, the error excerpt and a suggested fix, or comments on the existing ticket so you never get duplicates.
- Emails your on-call engineer for live site failures only, so preview and branch builds are tracked quietly without waking anyone.
What do I need to use this?
- A Netlify account containing the sites you want watched
- A Linear workspace, and the team where these tickets should be filed
- A Gmail account to send from, plus the email address of whoever is on call
How can I customize it?
- Decide which sites are in scope, and whether preview and branch failures get tracked at all or are ignored completely
- Change who receives the email, for example a shared on-call inbox rather than one person
- Adjust the list of likely causes to match how your builds actually break, such as adding a failing test step
FAQs
Will this email me every time a build fails?
How does it avoid filing the same ticket over and over?
Can it actually tell me why the deploy broke?
Does it matter whether my code is on GitHub, GitLab or Bitbucket?
What happens if the cause is not obvious?
Related templates
Every 15 minutes, forwarded phishing reports get traced back to the server that really sent them, with a verdict in Slack and the worst senders reported.
On the first Monday of every month, find the alarms nobody watches and the monitoring you quietly pay for, then get a costed cleanup list in Slack and Linear.
Every Thursday, rank your team's upcoming flights by how likely they are to run late, and email the fixes while changes are still cheap.
Each month, spot the saved cards about to expire, email the customers still on recurring billing, and rank the revenue at risk in Slack.
Every weekday morning, harmless address typos get fixed on unshipped orders, and anything undeliverable is held while the customer confirms it.
Every weekday morning, unfulfilled orders get an address check: harmless typos fixed automatically, risky addresses held with a note to the customer.
Stop guessing why your site failed to deploy.
Every failed build arrives already diagnosed, already written up, and already checked against what broke last time.