# Find Why a Vercel Deploy Broke an Astro Site Yes. An agent reads the broken and previous Vercel deployments through your Vercel connection, diffs their commits, and names the change that broke it in a report. [Run this on Rush](https://cloud.getrush.ai/run/investigate-vercel-deploy/astro/), in a Project that has your repository. ## What the agent does The run names the repository and a Vercel connection. In a monorepo like withastro/starlight the agent first maps how the site builds: `pnpm-workspace.yaml` makes `docs/` its own package, `starlight-docs`, whose `package.json` pins `astro` to `^7.2.10`, pulls `@astrojs/starlight` as `workspace:*` and `sharp` `^0.35.3` for images. The build command is plain `astro build`, and the root `package.json` fixes the toolchain at `packageManager: pnpm@11.22.0`, matching the Node `22.23.1` the CI workflows in `.github/workflows/ci.yml` install. It checks out both deployment commits so every file it cites was in the deploy. Through the Vercel connection, the official OAuth MCP server at `https://mcp.vercel.com`, the agent lists the project's deployments, takes the broken production deployment and the previous one with a READY state, and reads the build log of each. For an Astro 7 docs site like Starlight's that log is where `astro build` runs over 17 configured locales in `docs/astro.config.mjs`, so a build that failed during page data loading or at the link-checking step (`starlight-links-validator` runs as an integration) shows up there. It reads the broken deployment's runtime logs too, so a build that succeeded but serves 500s is separated from one that never deployed. Then it works out what changed. Each Vercel deployment records its commit sha, which the agent matches against the clone and diffs with `git log --oneline ..` and `git diff ..`. In a Starlight-shaped repository the files that decide whether the site renders are `docs/astro.config.mjs` (the `site` value built from environment variables, `trailingSlash: 'always'`, the `locales` object, the `head` entries that inject the analytics script and `og:image` meta), `docs/src/content.config.ts` (the `docsLoader` and `i18nLoader` schemas), and the `docs/package.json` pins. The agent narrows the diff to those, and where the logs alone do not settle it, it reproduces the failure in its sandbox with `pnpm install --frozen-lockfile`, `pnpm astro sync` and `astro build` inside `docs/`, the same commands `.github/workflows/ci.yml` runs. It changes no code, as the prompt says. What it writes is a report that names the one change that broke production, quotes the build and runtime log lines that point at it, and gives a roll-forward path: revert the commit or the specific hunk, or the smallest forward fix, with the file and config key to touch. ## Start it with one API call `POST https://api.prix.dev/o/{org}/sessions` ```json { "agent": "claude", "input": "Production broke after the latest deployment. Through the Vercel connection, compare its build output and runtime logs with the previous good deployment, diff the commits between them in this repository, and write a report naming the change, the evidence and how to roll forward. Change no code.", "resources": [ { "url": "https://github.com/your-org/your-app" } ] } ``` 1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token. 2. **Send the request.** POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox. 3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory. ## What comes back What comes back is an artifact, a Markdown report such as `deploy-investigation.md`, listed on the finished session with its own download URL. Its sections walk the comparison in order: the two deployments, each with its id, URL, state and commit sha; what the build logs of the broken one show that the previous good one does not; what the runtime logs add; the commit diff between them, reduced to the files that matter, with the change that broke it quoted; the evidence tying that change to the failure; and a roll-forward section that names the file to revert or fix. Because the run changed nothing, the session's `changes` read comes back empty and the proof is in the trajectory. `GET /o/{org}/sessions/{id}/messages` carries every event, including each Vercel log line the agent read through the connection, the `git log` and `git diff` output, and the output of any `astro build` it ran to reproduce the failure, so a reviewer can check the report's claims against the raw evidence without re-running anything. ## Run it on every failed production deploy Point a Vercel deployment webhook at your server and, on a production deployment whose state is not READY, have your server start this same run, naming the repository and the Vercel connection in the request. Each broken deploy gets its own session in its own sandbox, so a Friday deploy and the one after it are each investigated against its own previous good deployment. Set a webhook URL on the API key and Rush POSTs `run.completed` or `run.failed` when the turn finishes, with the session URL, so your server can page the on-call with a link to the report. A key runs at most `max_concurrent` sessions at once (4 by default) and answers `429` past that; a burst of failing deploys should queue. Because the run names a repository in `resources`, the Rush GitHub App must be installed on that repository for the clone to succeed. ## Why run it on Rush? Investigating a broken Astro deploy on a laptop means checking out two commits of a pnpm monorepo, pulling build and runtime logs out of the Vercel dashboard by hand, and often re-running `pnpm install` and `astro build` across a 17-locale site all on the machine you are trying to ship from. On Rush the agent does that in its own sandbox with its own clone: the Vercel connection gives it the logs, the repo gives it the commits, and any reproduction with `pnpm astro sync` and `astro build` runs there and parks when the turn ends. Your working tree and your Vercel session are untouched. The report is checkable rather than claimed. The trajectory keeps every log line the agent read and every command it ran with its output, and since it changes no code, the session's diff read is empty by construction. Several deploys can be under investigation at once, which is what a bad release day looks like; and because the run names the connection rather than carrying credentials, the Vercel sign-in an admin did once covers every run the key starts. ## Frequently asked questions ### How does the agent reach my Vercel deployments? An admin signs in once: Vercel is an official OAuth MCP server at `https://mcp.vercel.com`, so it connects through `POST /me/connections` the same way any OAuth MCP server does. After that, naming `"vercel"` in the run's `connections` field gives the agent the connection; no token goes into the request or the sandbox. ### How does it pick the deployments to compare? Through the connection it lists the project's deployments and takes the broken production deployment named in the incident plus the previous production deployment with a READY state. Each deployment records its commit sha, which it matches against the cloned repository, so the `git diff` it runs is exactly the commits between the two builds. ### Will it modify my repository? No. The prompt says to change no code and the deliverable is a report. You can confirm: a session's `changes` read lists files the agent changed, and for this job it is empty. The only write is the report artifact on the session. ### What if the build logs do not show the cause? Then it reads further instead of guessing: the broken deployment's runtime logs through the same connection, and a reproduction in the sandbox. For a Starlight-shaped repo it runs `pnpm install --frozen-lockfile`, `pnpm astro sync` and `astro build` in `docs/`, the same commands the CI workflows run, and reports the error it sees with the file that produced it. ### What does the roll-forward section look like? It names the exact change that broke production, quoted from the diff, and the smallest way back: reverting that commit or hunk, or a forward fix with the file and config key to change, such as a `site` value or a locale entry in `docs/astro.config.mjs`. It does not apply the fix; that is a follow-up run or your own commit.