Performance Budgets

Performance budgets turn Site Health into a gate in your deploy pipeline. Set thresholds once, then have your CI system call the budget-check API. If the site blows the budget, the build fails.

Budget fields

Each site has three budget settings, stored on the site row and editable in the site's settings panel.

Field	Type	What it enforces
Performance score (min)	0-100	Lighthouse Performance must be at least this.
LCP (max ms)	integer	Largest Contentful Paint must be at most this.
CLS (max)	float	Cumulative Layout Shift must be at most this.

Leave a field blank and that dimension isn't enforced.

The budget-check endpoint

The same budgets are evaluated by an authenticated API endpoint your CI system can hit.

Endpoint:

POST /api/external/budget-check
Authorization: Bearer <API_KEY>

Request body (optional):

{
  "siteId": "wf_abc123",
  "scanId": "optional-specific-scan-id"
}

If you don't pass scanId, the endpoint uses the site's latest completed scan.

Response:

{
  "pass": false,
  "scores": {
    "performance": 74,
    "lcp": 3100,
    "cls": 0.08
  },
  "violations": [
    { "metric": "performance", "budget": 80, "actual": 74 },
    { "metric": "lcp", "budget": 2500, "actual": 3100 }
  ]
}

Exit code logic for your CI script: fail the build when pass === false.

Alert rules are evaluated too

In addition to the three budget fields, the endpoint also evaluates any alert rules you've set on the site. One source of truth: the rules that email you are the same rules that fail your build.

Getting an API key

1. Open Settings → API Keys.
2. Click Create key.
3. Copy the raw key immediately — it's SHA-256 hashed at rest and won't be shown again.
4. Store it as a CI secret (e.g. SITE_HEALTH_API_KEY).

Keys are shown once

We don't keep the raw key. If you lose it, you'll need to rotate. Names/descriptions are visible forever; the secret itself is one-shot.

GitHub Actions

The full workflow lives at GitHub Actions integration. Short version:

- name: Check Site Health budgets
  run: |
    curl -sf -X POST https://sitehealth.octagramlabs.com/api/external/budget-check \
      -H "Authorization: Bearer $SITE_HEALTH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"siteId":"${{ vars.SITE_ID }}"}'
  env:
    SITE_HEALTH_API_KEY: ${{ secrets.SITE_HEALTH_API_KEY }}

curl -f exits non-zero on HTTP 4xx, so failed budgets fail the build automatically.

What's next

• Wire up GitHub Actions to run the check on every PR.
• Pair with regression detection so even budget-passing deploys get watched.