---
name: vercel
description: Set up a Codex monitor for Vercel deployments and preview URLs. Use when the user invokes /vercel or $vercel, asks Codex to watch or monitor a Vercel deployment, waits for a Vercel preview or PR preview to become ready, or wants to be notified with both the deployment URL and preview URL once Vercel is READY.
---
# Vercel Monitor
Monitor one immutable Vercel deployment for the `remotion` project and notify the
current task when that exact deployment becomes ready or fails.
## Non-negotiable rules
- Never infer deployment state from an HTTP response. A branch preview alias can
return 200 from the previous deployment while the new deployment is building.
- Never monitor a branch preview alias. It is movable and can resolve to an older
or newer deployment.
- Pin the monitor to a Vercel deployment ID (`dpl_...`) or the immutable automatic
deployment hostname (`<project>-<random>-<scope>.vercel.app`).
- Read the machine-readable Vercel deployment state. Do not parse human CLI output.
- Default to the `remotion` project and the `remotion` Vercel scope. Ignore the
`bugs` project unless the user explicitly asks for it.
## Resolve the exact deployment
Prefer these sources, in order:
1. A Vercel deployment/dashboard URL supplied by the user.
2. The `Vercel – remotion` check on the active GitHub PR. Its dashboard URL has
the form `https://vercel.com/remotion/remotion/<deployment-id-suffix>`.
3. The `remotion` row in the Vercel bot's PR comment.
4. `vercel list remotion --scope remotion --format=json`, matched to the exact PR,
commit SHA, or branch in `.deployments[].meta`.
The final path segment of a dashboard URL becomes the deployment ID by prefixing
it with `dpl_`. For example:
```text
https://vercel.com/remotion/remotion/AbCd1234 -> dpl_AbCd1234
```
The `Preview` link in a Vercel PR comment is normally a branch alias. Preserve it
for the final notification, but do not use it for state checks.
When using `vercel list`, select the newest deployment that matches all available
identity fields:
- `.name == "remotion"`
- `.meta.githubPrId == <PR number>`, when a PR is known
- `.meta.githubCommitSha == <full commit SHA>`, when a commit is known
Do not silently fall back to a different commit. If no exact deployment can be
identified, ask for the Vercel dashboard URL, PR number, or commit SHA.
## Read state
Run the bundled checker from the repository root:
```bash
python3 .agents/skills/vercel/scripts/check-deployment.py <deployment-id-or-url>
```
The checker calls:
```bash
vercel inspect <deployment-id-or-immutable-url> \
--scope remotion \
--format=json
```
It validates the project, rejects moving aliases, and emits normalized JSON.
Use its `state` field:
- `READY`: success.
- `ERROR`, `CANCELED`, or `CANCELLED`: failure.
- `BUILDING`, `QUEUED`, or `INITIALIZING`: still in progress.
- `UNKNOWN`: not terminal. Report the diagnostic only if it persists or prevents
creation of a trustworthy monitor.
HTTP probing may be used after `READY` as an optional reachability check. It must
never promote a non-ready or unknown deployment to `READY`.
## Create the monitor
Use the Codex automation tool to create a one-minute heartbeat with a bounded
count, normally 30 attempts. The heartbeat prompt must be self-contained and
include:
- The pinned deployment ID or immutable deployment hostname.
- The dashboard URL.
- The branch preview alias, if known, for the final notification only.
- The project, PR, branch, and commit context, if known.
- The exact checker command.
- The terminal-state rules above.
Use this prompt shape:
```text
Monitor this exact Vercel deployment until it reaches a terminal state.
Pinned deployment: <dpl_id_or_immutable_hostname>
Dashboard: <dashboard_url>
Preview alias (reporting only; never use for state): <preview_url_or_unknown>
Context: <project/pr/branch/commit>
From the repository root, run:
python3 .agents/skills/vercel/scripts/check-deployment.py <pinned_deployment>
Only the JSON `state` is authoritative.
- READY: reply "Vercel deployment is ready" and include Dashboard and Preview.
- ERROR, CANCELED, or CANCELLED: reply with the failure state and include both links.
- BUILDING, QUEUED, INITIALIZING, or UNKNOWN: stay quiet and check again next time.
Never curl the preview URL to determine readiness. After reporting a terminal
state, delete or pause this heartbeat if its automation ID is available.
```
Before creating a heartbeat, run the checker once. If the deployment is already
terminal, report immediately instead. Otherwise, tell the user which exact
deployment is being watched and the cadence.