Netlify Deploy Failure Sentinel for Kestra

id: netlify-deploy-failure-sentinel
namespace: company.team
description: |
  Every hour, read the recent deploys of one Netlify site (read-only: nothing
  is built, published, locked or rolled back) and classify deploy health as
  HEALTHY, WARNING, CRITICAL, LOW_VOLUME or UNREACHABLE. Log quiet runs and
  alert Slack when the latest production deploy failed, when deploys keep
  failing, or when a build has been stuck for too long.

inputs:
  - id: site_id
    type: STRING
    defaults: "your-site-id"
    displayName: "Netlify Site ID"
    description: "The site's API ID (Site configuration > General > Site details),
      or its netlify.app subdomain."
  - id: lookback_hours
    type: INT
    defaults: 24
    displayName: "Lookback Window (hours)"
    description: "Judge deploys created in the last this many hours."
  - id: warning_failure_rate
    type: FLOAT
    defaults: 20.0
    displayName: "Warning Failure Rate (%)"
    description: "At or above this share of failed deploys among finished ones in
      the window, the check is WARNING."
  - id: stuck_minutes
    type: INT
    defaults: 45
    displayName: "Stuck Build Threshold (minutes)"
    description: "A deploy still queued or building after this many minutes counts
      as stuck and makes the check WARNING."

triggers:
  - id: hourly_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check deploys every hour. Shipped disabled; enable it once the
      Netlify token secret and the site ID are set and a manual run has been
      verified.
    cron: "25 * * * *"
    disabled: true

tasks:
  - id: list_deploys
    type: io.kestra.plugin.core.http.Request
    description: Read the most recent page (up to 100) of deploys for the site from
      the Netlify API. This is a GET; nothing is built, published, locked or
      rolled back.
    uri: "https://api.netlify.com/api/v1/sites/{{ inputs.site_id
      }}/deploys?per_page=100"
    method: GET
    headers:
      Authorization: "Bearer {{ secret('NETLIFY_AUTH_TOKEN') }}"
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT10S
      maxAttempts: 3
    allowFailure: true

  - id: summarize_deploys
    type: io.kestra.plugin.core.debug.Return
    description: Keep deploys created in the lookback window, compute the share that
      ended in error among finished ones, find the latest finished production
      deploy and the most common error, count builds stuck past the threshold,
      and classify in one jq query. A missing or non-200 response becomes
      UNREACHABLE.
    format: >-
      {{ (outputs.list_deploys.code is not defined or outputs.list_deploys.code
      != 200) ?
      '{"status":"UNREACHABLE","finished":0,"ready":0,"failed":0,"rate":0,"in_flight":0,"stuck":0,"production":"none","production_error":"none","top_error":"none"}'
      : (fromJson(outputs.list_deploys.body) | jq(' "' ~ (now() |
      dateAdd(-inputs.lookback_hours, 'HOURS') | date("yyyy-MM-dd'T'HH:mm:ss",
      timeZone="UTC")) ~ '" as $since | "' ~ (now() |
      dateAdd(-inputs.stuck_minutes, 'MINUTES') | date("yyyy-MM-dd'T'HH:mm:ss",
      timeZone="UTC")) ~ '" as $stuck_before | [.[] | select((.created_at // "")
      >= $since)] as $d | [$d[] | select(.state == "ready" or .state ==
      "error")] as $f | [$f[] | select(.state == "error")] as $bad | [$d[] |
      select(.state != "ready" and .state != "error" and .state != "rejected"
      and (.skipped // false) == false)] as $open | [$open[] |
      select((.created_at // "") < $stuck_before)] as $stuck | ([.[] |
      select(.context == "production" and (.state == "ready" or .state ==
      "error"))] | sort_by(.created_at) | last) as $prod | ($f | length) as $n |
      (if $n == 0 then 0 else ((($bad | length) * 1000 / $n) | floor) / 10 end)
      as $r | {finished: $n, ready: ($n - ($bad | length)), failed: ($bad |
      length), rate: $r, in_flight: ($open | length), stuck: ($stuck | length),
      production: (if $prod == null then "none" else (($prod.state) + " " +
      (($prod.branch // "?") | tostring) + "@" + ((($prod.commit_ref //
      "manual") | tostring) | .[0:7])) end), production_error: (if $prod == null
      or $prod.state != "error" then "none" else ((($prod.error_message // "no
      error message") | tostring | split("\"") | join("") | split("\n") | join("
      ") | .[0:120])) end), top_error: (if ($bad | length) == 0 then "none" else
      ([$bad[] | ((.error_message // "no error message") | tostring |
      split("\"") | join("") | split("\n") | join(" ") | .[0:100])] |
      group_by(.) | map({e: .[0], c: length}) | max_by(.c) | (.e + " (x" + (.c |
      tostring) + ")")) end), status: (if $prod != null and $prod.state ==
      "error" then "CRITICAL" elif ($n > 0 and $r >= ' ~
      inputs.warning_failure_rate ~ ') or ($stuck | length) > 0 then "WARNING"
      elif $n == 0 then "LOW_VOLUME" else "HEALTHY" end)} ') | first | toJson)
      }}

  - id: route_by_deploys
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when deploys are healthy or there were none in
      the window, a Slack message when failures cross the warning line or a
      build is stuck, or a Slack page when the latest production deploy failed
      or Netlify could not be read.
    value: "{{ fromJson(outputs.summarize_deploys.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          description: Log a quiet line when the check is healthy; no Slack message is sent.
          message: "Netlify deploys healthy for {{ inputs.site_id }}: {{
            fromJson(outputs.summarize_deploys.value).failed }} of {{
            fromJson(outputs.summarize_deploys.value).finished }} finished
            deploys failed in the last {{ inputs.lookback_hours }} hour(s);
            production is {{
            fromJson(outputs.summarize_deploys.value).production }}."
      "LOW_VOLUME":
        - id: log_low_volume
          type: io.kestra.plugin.core.log.Log
          description: Log a quiet line when no deploy finished in the window; no Slack
            message is sent.
          message: "Netlify deploys for {{ inputs.site_id }}: no deploy finished in the
            last {{ inputs.lookback_hours }} hour(s); production is {{
            fromJson(outputs.summarize_deploys.value).production }}."
      "WARNING":
        - id: alert_warning_deploys
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post a Slack message when the deploy failure rate is at or above
            the warning line or a build is stuck.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Netlify deploys WARNING for {{ inputs.site_id }}: {{ fromJson(outputs.summarize_deploys.value).failed }} of {{ fromJson(outputs.summarize_deploys.value).finished }} finished deploys failed ({{ fromJson(outputs.summarize_deploys.value).rate }}%) in the last {{ inputs.lookback_hours }} hour(s), {{ fromJson(outputs.summarize_deploys.value).stuck }} build(s) stuck for more than {{ inputs.stuck_minutes }} minutes. Most common error: {{ fromJson(outputs.summarize_deploys.value).top_error }}. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_production
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the latest finished production deploy failed,
            because the live site is still serving an older build and the change
            never shipped.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Netlify production deploy FAILED for {{ inputs.site_id }}: latest production deploy is {{ fromJson(outputs.summarize_deploys.value).production }} with error: {{ fromJson(outputs.summarize_deploys.value).production_error }}. The live site is still on the previous build. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_api
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the deploy list could not be read, indicating an
            outage, a wrong site ID or an invalid token.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Netlify deploy sentinel UNREACHABLE for {{ inputs.site_id }}: the deploy list did not return a usable response (HTTP {{ outputs.list_deploys.code ?? 'no response' }}). Check the site ID and the access token. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        description: Fallback for any classification the cases above do not cover, so an
          unexpected value is visible in the logs.
        message: "Netlify deploy sentinel completed with an unexpected classification:
          {{ outputs.summarize_deploys.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record one audit line for every run, whichever branch fired, so the
      deploy history stays queryable even if Slack delivery fails.
    message: "Netlify deploy sentinel audit: site={{ inputs.site_id }}
      lookback_hours={{ inputs.lookback_hours }} http={{
      outputs.list_deploys.code ?? 'n/a' }} summary={{
      outputs.summarize_deploys.value }} execution={{ execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails, so a broken check
      is never mistaken for healthy deploys.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "Netlify deploy sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Deploy health is now unknown; check the task logs and the Netlify deploys page."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ fromJson(outputs.summarize_deploys.value).status }}"

When a Netlify production deploy fails, nothing looks broken: the site keeps serving the last good build, the merge is green in Git, and the only trace is a red deploy in the Netlify UI that nobody is watching. The fix the team thinks is live never shipped. The same happens more quietly with deploy previews that fail on every branch, or a build that sits in the queue for an hour. This blueprint turns a scheduled, read-only call to the Netlify API into a deploy health gate: io.kestra.plugin.core.http.Request reads the site's recent deploys, one jq query finds the latest production result, the failure rate and builds that are stuck, and the result routes to a quiet log or a Slack alert.

How it works

list_deploys (io.kestra.plugin.core.http.Request) calls GET /api/v1/sites/{site_id}/deploys?per_page=100 with a bearer token, which returns the most recent deploys of every context (production, deploy previews, branch deploys). It is a read: nothing is built, published, locked or rolled back. Retries cover short network blips, and allowFailed plus allowFailure keep an API error from aborting the flow so it can be reported instead.
summarize_deploys (io.kestra.plugin.core.debug.Return) first guards for a missing or non-200 response (UNREACHABLE). Otherwise one jq query keeps deploys whose created_at is inside the lookback window, treats ready and error as finished, and counts other non-skipped states (enqueued, building, uploading, processing, ...) as in flight, flagging the ones older than stuck_minutes. It also picks the latest finished deploy with context == "production" from the whole page. A failed latest production deploy is CRITICAL; a failure rate at or above warning_failure_rate, or any stuck build, is WARNING; no finished deploy in the window is LOW_VOLUME; otherwise HEALTHY.
route_by_deploys (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY and LOW_VOLUME log quietly, WARNING posts a Slack note, CRITICAL and UNREACHABLE page Slack. A defaults fallback logs anything unexpected.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run with the HTTP status and the full summary.
The flow-level errors block pages Slack if the flow itself fails, and the hourly_check trigger runs at 25 minutes past every hour, shipped disabled: true.

What you get

An hourly, read-only check of a Netlify site's deploys with no custom scripting and no extra plugin to install.
A status output (HEALTHY / WARNING / CRITICAL / LOW_VOLUME / UNREACHABLE) other flows can gate on, for example to hold a release announcement until production really deployed.
Slack messages with the production branch and commit, the Netlify error message, the failure rate and the number of stuck builds.
An audit line on every run, separate from Slack.

Who it's for

Frontend and platform teams that ship sites and apps on Netlify.
Agencies running many client sites, one execution per site ID.
Teams that already run their release and alerting workflows in Kestra.

Why orchestrate this with Kestra

Netlify can email or post a notification per deploy event, but it does not tell you that the last production deploy is still failing an hour later, that one deploy in three fails, or that a build has been queued for 45 minutes. Kestra turns a plain, read-only API call into a scheduled, typed classification with retries, a failure path and an execution history, and the same flow runs against any number of sites by changing site_id.

Prerequisites

A Netlify site and a personal access token from User settings > Applications (read access to the team that owns the site).
The site's API ID from Site configuration > General > Site details.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE and flow-failure alerts.

Secrets

NETLIFY_AUTH_TOKEN: a Netlify personal access token for a user on the team that owns the site.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS, secrets are supplied as environment variables prefixed SECRET_ and base64-encoded, for example SECRET_NETLIFY_AUTH_TOKEN=$(echo -n 'your-netlify-token' | base64), and read back with {{ secret('NETLIFY_AUTH_TOKEN') }}. Use the Enterprise secrets backend for encryption at rest and access control.

Quick start

Add NETLIFY_AUTH_TOKEN and SLACK_WEBHOOK as secrets.
Set site_id and run the flow manually; compare the counts and the production line in the logs with the site's Deploys page.
Push a commit that breaks the build on a branch to see a failure counted, then revert it.
Enable hourly_check.

How to extend

Loop over several sites with io.kestra.plugin.core.flow.ForEach and one site_id per item.
Judge production only by filtering the jq on context == "production", or give deploy previews their own limit.
Store the last production deploy ID in a KV store and alert only when a new failure appears.
Trigger a retry with POST /api/v1/sites/{site_id}/builds from a separate, approved flow when production failed on a transient error.

Inputs

site_id: type STRING, default your-site-id.
lookback_hours: type INT, default 24.
warning_failure_rate: type FLOAT, default 20.0 (percent).
stuck_minutes: type INT, default 45.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, LOW_VOLUME, UNREACHABLE.
Example path: {{ fromJson(outputs.summarize_deploys.value).production_error }} for the error of a failed production deploy.

Pitfalls

Only the first page (100 deploys, newest first) is read; a site with more than 100 deploys in the window needs page paging or a shorter window.
The production result comes from the latest finished production deploy on that page, so a site with no production deploy in its last 100 deploys reports none.
This flow only reads; it never triggers a build, publishes, locks or restores a deploy.