Skip to content

SOP-058 — Deploy pipeline (Vercel) — Platform Engineer

Guide

<!-- last-reviewed: 2026-06-01 · owner: Engineering (Platform Engineer) -->

SOP-058 — Deploy pipeline (Vercel) — Platform Engineer

SOP · owner: Engineering (Platform Engineer). Layer: SOP/Runbook (docs/canon.md). Runs and verifies the Vercel deploy from the Engineering side. The deploy shape (intranet/vercel.json) is ours; the CI/build-skip tooling (vercel-ignore.sh, .github/workflows/) is Operations’ — we propose changes, we do not own it. Account-level steps are the Principal’s (SOP-003). This SOP links SOP-003 rather than restating it.

Interface Contract

  • Inputs: reviewed release to deploy ← from <Engineering Director (SOP-055)> · trigger: review passed
  • Outputs: deploy-verified release → to Archivist (release note) · trigger: artifact approved
  • Handoff trigger (in): a reviewed, build-green release is ready to ship at a checkpoint
  • Handoff trigger (out): the deploy is READY, build-verified, auth-gated, and recorded
  • Definition of Done before handoff:
    • [ ] cd intranet && npm run build green locally at the release commit (~50 pages, [sync] …)
    • [ ] Push batched to a deliberate checkpoint (GR-7); not per-commit (ADR-0009, 100/day)
    • [ ] Vercel deployment READY; build log shows the [sync] … line + page count
    • [ ] Site fetched unauthenticated → Vercel login interstitial (auth gate on, ADR-0008)
    • [ ] Function health checked (/api/heartbeat responds behind auth)
    • [ ] Release note handed to the Archivist (artifact approved) if one was authored

Trigger phrases drawn from docs/handoff-triggers.md. The review passed in-edge is the Director’s release hand-down (SOP-055). Account-level Vercel steps (project import, Deployment Protection) are the Principal’s and are exempt (Principal edge, interface-contract-spec.md §3.1 R2).

Purpose

Get a reviewed release live on Vercel — single-user, budget-safe, and verified — without burning the daily deploy budget or shipping a broken function.

When to use

When the Engineering Director hands a reviewed, build-green release (SOP-055) at a deliberate checkpoint. Never deploy mid-task (GR-7).

Flow

flowchart LR
  A["review passed<br/>(release)"] --> B["build green<br/>locally"]
  B --> C["batch push to main<br/>(checkpoint)"]
  C --> D{"deploy READY?<br/>auth gate on?"}
  D -->|no| E["investigate<br/>build log"]
  D -->|yes| F["verify function<br/>+ record"]
  E --> C
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,B,C,E,F s
  class D d

Text fallback: a reviewed release arrives (review passed) → confirm the build is green locally → batch-push to main at a checkpoint → confirm the Vercel deploy is READY and the auth gate is on (unauthenticated fetch → login interstitial) → verify function health and record; if not READY, read the build log and reconcile.

Steps

  1. Confirm review + build. Release passed SOP-055; npm run build green locally.
  2. Confirm the build-skip allowlist covers the changed paths (intranet/scripts/vercel-ignore.sh) — a path not on the allowlist is silently skipped. If a new portal-relevant path landed, propose the allowlist edit to the Process Engineer (Operations owns the script).
  3. Batch the push (GR-7). Promote to main once per checkpoint — each push is a deploy against the 100/day ceiling (ADR-0009).
  4. Verify the deploy (SOP-003 step 5): deployment READY; build log shows the [sync] … line + page count.
  5. Verify the auth gate: fetch the URL unauthenticated → expect the Vercel login interstitial, not the dashboard (ADR-0008).
  6. Verify function health: /api/heartbeat responds behind auth; getDb() does not throw (i.e. DATABASE_URL is set in the Vercel project env, not the repo).
  7. Record + hand off any release note to the Archivist (artifact approved).

Roles / approvers

Account-level Vercel steps: Principal (SOP-003 steps 1–3). Deploy run + verification: Platform Engineer. Release approval: Engineering Director (SOP-055). CI/build-skip tooling: Operations (propose changes, do not edit).

Guardrails

  • Never push mid-task (GR-7); each main push deploys and consumes budget.
  • No secrets in the repo/bundle (security.md, SOP-004) — DATABASE_URL is a Vercel env var; spot-check dist for PA personal info.
  • Pipeline tooling is Operations’ — propose vercel-ignore.sh / workflow changes to the Process Engineer.
  • Security/auth posture is policy (ADR-0008) — flag changes to the Principal (Security unstaffed); do not alter it.

Job aid: docs/units/engineering/job-aids/JA-058-deploy-intranet-steps.md. See also: docs/units/engineering/manuals/platform-engineer.md · SOP-055 · SOP-059 · docs/sop/deploy-intranet.md (SOP-003) · ADR-0008 / ADR-0009 · docs/handoff-triggers.md.