web-release — production serves the build you tested, and the previous one is one command away
A frontend release fails quietly: the command exits 0, the CDN keeps the old bundle, a
_headers file is ignored, or the build picked up an uncommitted file. The rule is the
same as for any artifact: build once, test that build, promote that build.
1. Build from what CI checked
git status --porcelain empty and HEAD = the commit whose CI is green (all checks,
browser E2E included). The bundler packs the directory, not HEAD: another session's
uncommitted edit would ship.
- Inject the commit into the bundle so it can be read back:
NEXT_PUBLIC_BUILD_SHA,
VITE_BUILD_SHA, or a generated public/version.json { "sha": "<40 hex>", "builtAt": … }.
- Use the lockfile (
npm ci, pnpm i --frozen-lockfile), never a fresh resolve.
2. Preview first, always
| Host |
Preview |
Its immutable id |
| Vercel |
vercel deploy (no --prod) or the git preview |
deployment URL / dpl_… id |
| Cloudflare Pages |
wrangler pages deploy <dir> --branch <non-prod> |
deployment id + <hash>.<project>.pages.dev |
| Workers static assets |
wrangler versions upload |
version id (not yet deployed) |
| S3 + CDN |
upload to a versioned prefix releases/<sha>/ |
the prefix |
Then e2e-test-engineer runs the Playwright golden paths against that preview URL.
A local next start or a rebuild is a different artifact and is not evidence.
3. Promote — after gate:release
Promotion makes the tested deployment the production one. It does not rebuild.
| Host |
Promote |
Rollback (record it before promoting) |
| Vercel |
vercel promote <deployment-url> (or alias assign) |
vercel promote <previous-deployment-url> / vercel rollback |
| Cloudflare Pages |
promote the deployment to production in the project (or deploy the same dir with --branch <production branch>) |
rollback to the previous production deployment id |
| Workers |
wrangler versions deploy <version-id>@100% |
wrangler versions deploy <previous-id>@100% / wrangler rollback |
| S3 + CDN |
switch the origin path / index.html pointer to releases/<sha>/ |
point back to releases/<previous-sha>/ |
- Never
vercel --prod from a working tree as "the promote": that is a new build nobody tested.
- Gradual rollout where the host supports it (Vercel rolling releases, Workers percentage
deploy): start small, decide on a named signal (error rate, Web Vitals for this
deployment), then 100 %.
- The production domain and its DNS are infra-provisioner's. Missing domain → stop, route there.
4. Prove it landed
- The production URL's
/version.json (or the build-sha meta tag) returns the promoted
sha. Read it from outside the CDN edge cache — a cache-busting query — and read the
age / cf-cache-status / x-vercel-cache response header.
- HTML is served fresh (
cache-control: no-cache or short max-age); hashed assets are
immutable. A long max-age on index.html keeps users on the old build for its full life.
- Purge only what changed (tags / paths), not the whole zone, and only when the host does
not version automatically.
- Core journeys on production (Playwright smoke, logged in where the product needs it).
- Source maps: uploaded to the error tracker for this sha, not served publicly
unless the project chose that.
5. Keep one rollback, clean the rest
Hosts keep deployments; your machine keeps dist/, .next/, .vercel/output, out/.
After the release: keep the live deployment and the previous one; delete local build
output of older releases by exact path (artifact-retention).
Report
WEB-RELEASE <project> @ <sha>
ci : PASS — all checks green on <sha> (run <id>)
preview : PASS — <deployment url / id>
e2e : PASS — playwright 9/9 on the preview URL
promote : PASS — after gate:release (<gate id>)
landed : PASS — /version.json = <sha>, cache MISS→HIT
rollback : vercel promote <previous deployment url>
1---2name: web-release3description: Release a web frontend (Vercel, Cloudflare Pages / Workers static assets, S3/CDN, Netlify) so that production serves exactly the build that was tested, and rolling back is one named command. Covers clean-tree builds, immutable preview deployments, E2E on the preview URL, promote by alias or route switch, build-id proof, cache purge, source maps, and rollback by re-aliasing the previous deployment. Use for any frontend ship step ("выкати фронт", "промоутни в прод", "откати сайт", "почему на проде старая версия"). Loaded by release-manager.4when_to_use: |5 Apply when:6 - deploying a web frontend to preview, staging or production7 - promoting a preview deployment, or rolling production back8 - production serves an older build than expected9 Do NOT apply to:10 - backend services, containers, databases — that is devops11 - creating the hosting project, domain or DNS — that is infra-provisioner12effort: medium13allowed-tools: Read, Bash, Grep14metadata:15 source: https://skillmd.com/skills/tuyv/web-release16---1718# web-release — production serves the build you tested, and the previous one is one command away1920A frontend release fails quietly: the command exits 0, the CDN keeps the old bundle, a21`_headers` file is ignored, or the build picked up an uncommitted file. The rule is the22same as for any artifact: **build once, test that build, promote that build**.2324## 1. Build from what CI checked2526- `git status --porcelain` empty and `HEAD` = the commit whose CI is green (all checks,27 browser E2E included). The bundler packs the directory, not HEAD: another session's28 uncommitted edit would ship.29- Inject the commit into the bundle so it can be read back: `NEXT_PUBLIC_BUILD_SHA`,30 `VITE_BUILD_SHA`, or a generated `public/version.json` `{ "sha": "<40 hex>", "builtAt": … }`.31- Use the lockfile (`npm ci`, `pnpm i --frozen-lockfile`), never a fresh resolve.3233## 2. Preview first, always3435| Host | Preview | Its immutable id |36|---|---|---|37| Vercel | `vercel deploy` (no `--prod`) or the git preview | deployment URL / `dpl_…` id |38| Cloudflare Pages | `wrangler pages deploy <dir> --branch <non-prod>` | deployment id + `<hash>.<project>.pages.dev` |39| Workers static assets | `wrangler versions upload` | version id (not yet deployed) |40| S3 + CDN | upload to a versioned prefix `releases/<sha>/` | the prefix |4142Then `e2e-test-engineer` runs the Playwright golden paths **against that preview URL**.43A local `next start` or a rebuild is a different artifact and is not evidence.4445## 3. Promote — after `gate:release`4647Promotion makes the tested deployment the production one. It does not rebuild.4849| Host | Promote | Rollback (record it before promoting) |50|---|---|---|51| Vercel | `vercel promote <deployment-url>` (or alias assign) | `vercel promote <previous-deployment-url>` / `vercel rollback` |52| Cloudflare Pages | promote the deployment to production in the project (or deploy the same dir with `--branch <production branch>`) | rollback to the previous production deployment id |53| Workers | `wrangler versions deploy <version-id>@100%` | `wrangler versions deploy <previous-id>@100%` / `wrangler rollback` |54| S3 + CDN | switch the origin path / `index.html` pointer to `releases/<sha>/` | point back to `releases/<previous-sha>/` |5556- Never `vercel --prod` from a working tree as "the promote": that is a new build nobody tested.57- Gradual rollout where the host supports it (Vercel rolling releases, Workers percentage58 deploy): start small, decide on a named signal (error rate, Web Vitals for this59 deployment), then 100 %.60- The production domain and its DNS are infra-provisioner's. Missing domain → stop, route there.6162## 4. Prove it landed6364- The production URL's `/version.json` (or the build-sha meta tag) returns the promoted65 sha. Read it from outside the CDN edge cache — a cache-busting query — and read the66 `age` / `cf-cache-status` / `x-vercel-cache` response header.67- HTML is served fresh (`cache-control: no-cache` or short max-age); hashed assets are68 immutable. A long max-age on `index.html` keeps users on the old build for its full life.69- Purge only what changed (tags / paths), not the whole zone, and only when the host does70 not version automatically.71- Core journeys on production (Playwright smoke, logged in where the product needs it).72- Source maps: uploaded to the error tracker for this sha, **not** served publicly73 unless the project chose that.7475## 5. Keep one rollback, clean the rest7677Hosts keep deployments; your machine keeps `dist/`, `.next/`, `.vercel/output`, `out/`.78After the release: keep the live deployment and the previous one; delete local build79output of older releases by exact path (`artifact-retention`).8081## Report8283```84WEB-RELEASE <project> @ <sha>85 ci : PASS — all checks green on <sha> (run <id>)86 preview : PASS — <deployment url / id>87 e2e : PASS — playwright 9/9 on the preview URL88 promote : PASS — after gate:release (<gate id>)89 landed : PASS — /version.json = <sha>, cache MISS→HIT90 rollback : vercel promote <previous deployment url>91```