ContextQMD
Back to Remotion

Vercel Monitor

.agents/skills/vercel/SKILL.md

4.0.5084.2 KB
Original Source

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.