vercel

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.