vercel

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:

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:

python3 .agents/skills/vercel/scripts/check-deployment.py <deployment-id-or-url>

The checker calls:

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:

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.