Hold Every Release to a Lighthouse Score Budget

id: lighthouse-performance-budget
namespace: company.team
description: |
  Run Lighthouse against a freshly deployed URL, compare performance,
  accessibility, and best-practices scores against your budget, and alert
  Slack the moment a release ships a regression.

triggers:
  - id: perf_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Call this from the deploy pipeline right after the new version is
      live, so score regressions are caught while the release is still fresh.
    key: perf-budget-check
  - id: daily_budget_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Optional daily score watch to catch slow third-party regressions
      that arrive without a deploy. Shipped disabled.
    cron: "30 7 * * *"
    disabled: true

inputs:
  - id: url
    type: STRING
    defaults: https://example.com
    description: The page to audit, your production or staging URL after deploy.
  - id: min_performance
    type: FLOAT
    defaults: 0.5
    description: Minimum Lighthouse performance score (0.0-1.0).
  - id: min_accessibility
    type: FLOAT
    defaults: 0.5
    description: Minimum Lighthouse accessibility score (0.0-1.0).
  - id: min_best_practices
    type: FLOAT
    defaults: 0.5
    description: Minimum Lighthouse best-practices score (0.0-1.0).
  - id: lighthouse_image
    type: STRING
    defaults: node:20-bookworm
    description: Image used to run Lighthouse. Defaults to plain Debian Node,
      Chromium and Lighthouse are installed on first run. Point it at your own
      prebaked image to skip those installs.

tasks:
  - id: run_lighthouse
    type: io.kestra.plugin.scripts.shell.Commands
    description: Install Chromium and Lighthouse in a throwaway container, audit the
      URL headlessly, and publish the three category scores through Kestra's
      stdout outputs protocol. Lighthouse is pinned to major 12 for reproducible
      scoring, missing scores are coerced to 0 rather than null so budget
      comparisons can never silently pass, and container-level pitfalls are
      handled with --no-sandbox and --disable-dev-shm-usage.
    containerImage: "{{ inputs.lighthouse_image }}"
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    commands:
      - |
        set -eu
        export DEBIAN_FRONTEND=noninteractive
        apt-get update -qq >/dev/null 2>&1
        apt-get install -y -qq chromium >/dev/null 2>&1
        export CHROME_PATH=$(command -v chromium || command -v chromium-browser)
        npx --yes lighthouse@12 "{{ inputs.url }}" \
          --output=json \
          --output-path=/tmp/lighthouse-report.json \
          --quiet \
          --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
          --only-categories=performance,accessibility,best-practices
        node -e '
          const fs = require("fs");
          const report = JSON.parse(fs.readFileSync("/tmp/lighthouse-report.json", "utf8"));
          const score = (key) => {
            const cat = report.categories[key];
            return (cat && typeof cat.score === "number") ? cat.score : 0;
          };
          const outputs = {
            performance: score("performance"),
            accessibility: score("accessibility"),
            best_practices: score("best-practices"),
          };
          console.log("scores: " + JSON.stringify(outputs));
          console.log("::" + JSON.stringify({ outputs: outputs }) + "::");
        '

  - id: check_budget
    type: io.kestra.plugin.core.flow.If
    description: Compare all three scores against their budgets in one condition,
      any category under its floor means the release shipped a regression worth
      waking someone for.
    condition: "{{ outputs.run_lighthouse.vars.performance < inputs.min_performance
      or outputs.run_lighthouse.vars.accessibility < inputs.min_accessibility or
      outputs.run_lighthouse.vars.best_practices < inputs.min_best_practices }}"
    then:
      - id: alert_budget_breach
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Post each measured score next to its budget so the responder sees
          which category fell and by how much, not just that something did.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "Lighthouse BUDGET BREACH on {{ inputs.url }}, performance {{ outputs.run_lighthouse.vars.performance }} (min {{ inputs.min_performance }}), accessibility {{ outputs.run_lighthouse.vars.accessibility }} (min {{ inputs.min_accessibility }}), best-practices {{ outputs.run_lighthouse.vars.best_practices }} (min {{ inputs.min_best_practices }}). Check the release or its third-party scripts. Execution {{ execution.id }}."
          }
    else:
      - id: log_within_budget
        type: io.kestra.plugin.core.log.Log
        description: Record the three scores on every run so the execution history
          becomes the score trend across releases.
        message: "Lighthouse within budget on {{ inputs.url }}: performance {{
          outputs.run_lighthouse.vars.performance }}, accessibility {{
          outputs.run_lighthouse.vars.accessibility }}, best-practices {{
          outputs.run_lighthouse.vars.best_practices }}."

errors:
  - id: alert_audit_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert when the audit itself fails, site down, container cannot
      pull, Lighthouse crash, because no score must never be read as a passing
      score.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Lighthouse audit FAILED in flow {{ flow.id }} (execution {{ execution.id }}) for {{ inputs.url }}. No scores were produced, verify the URL is reachable from the Worker and the image in lighthouse_image is pullable."
      }

outputs:
  - id: score_summary
    type: JSON
    description: 'The three category scores, e.g. {"performance": 1,
      "accessibility": 0.92, "best_practices": 1}, ready for dashboards or a
      release gate.'
    value: "{{ outputs.run_lighthouse.vars | toJson }}"