What the agent does
An Astro site's CI usually has one job with several steps, so the agent first reads which step failed and what the step actually runs. In a site shaped like satnaing/astro-paper, .github/workflows/ci.yml runs on pull_request (opened, edited, synchronize and reopened) and on workflow_call, with one build job and timeout-minutes: 3: pnpm/action-setup@v4 at 11.3.0, actions/setup-node@v4 on Node 24 with the pnpm cache, pnpm install --frozen-lockfile, pnpm run lint, pnpm run format:check and pnpm run build. package.json makes those three concrete: lint is eslint ., format:check is prettier --check ., and build is astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/, so a red build step can be a type error, a content error, a rendering error or the search indexer, and the log's last lines say which. The agent reads gh run view <id> --log-failed, names the step and the first error, and notes whether the run was cut off by the three-minute timeout rather than by an error.
Then it reads what each step enforces. eslint.config.js applies eslint-plugin-astro's recommended rules, parses .astro and TypeScript with @typescript-eslint/parser, sets no-console to error, and ignores dist/, .astro/ and public/pagefind/. .prettierrc loads prettier-plugin-astro and prettier-plugin-tailwindcss, which means class order inside a class="..." attribute is a formatting error, not a style preference. tsconfig.json extends astro/tsconfigs/strict, so astro check fails on an implicit any in a frontmatter block. src/content.config.ts defines the posts collection with pubDatetime as a date, title and description required, tags defaulting to ["others"] and ogImage as an image or a string; a post with a missing description or a pubDatetime written as a bare string fails astro build at content loading, with the file name in the error. src/utils/postFilter.ts drops drafts and, in production builds, posts whose pubDatetime is further ahead than scheduledPostMargin, which is why a scheduled post can disappear from a build without failing it.
Reproduction uses the same versions. The agent enables Corepack and activates pnpm@11.3.0, runs on Node 24, and runs pnpm install --frozen-lockfile, which is itself a common cause: a dependency edited in package.json without pnpm-lock.yaml updated fails that step before any code runs, and the fix is the regenerated lockfile, not a change to the workflow. Then it runs pnpm run lint, pnpm run format:check and pnpm run build in the workflow's order. pagefind needs the built dist/, src/pages/og.png.ts and src/pages/posts/[...slug]/index.png.ts render Open Graph images with satori and sharp at build time, and astro.config.ts fetches the Google Sans Code font through Astro's font provider, so a build that fails at one of these steps fails for a reason the log states, and the agent reads that line before touching anything.
The fix is the smallest one: a frontmatter field in one post under src/content/posts, a type in one component under src/components or src/layouts, a console.log removed, pnpm format on the one file Prettier flagged, or the lockfile regenerated with the same pnpm. It does not raise timeout-minutes, loosen no-console, add an ignore to ESLint or make description optional in the schema to get green; when the cause really is the three-minute budget, it says so with the step timings from the log and proposes the change as a separate question. After the fix it reruns all three commands, and pnpm run build has to finish including Pagefind, because cp -r dist/pagefind public/ is the last thing the step does. The pull request names the run, quotes the failing lines and pastes the three commands with their output.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "The CI workflow for this Astro site failed; the failed workflow run follows this prompt. Read .github/workflows/ci.yml, package.json, eslint.config.js, .prettierrc, tsconfig.json, astro.config.ts, src/content.config.ts and src/utils/postFilter.ts, then read the failed job's log with gh run view <run id> --log-failed and name the step and the first error, or say that the job hit its timeout. Reproduce with the pnpm version the workflow pins and the Node version it sets: pnpm install --frozen-lockfile, then the lint, format:check and build scripts in the workflow's order. Make the smallest change that fixes the cause: a frontmatter field in a post, a type in a component, a removed console call, a formatted file, or a regenerated lockfile when package.json and the lockfile disagree. Do not raise the job timeout, relax an ESLint rule, add an ignore, or loosen the content schema; if the timeout is the real cause, explain it with the step timings and stop. Rerun all three scripts and make sure the build finishes through Pagefind. Open a pull request that names the failed run, quotes the failing lines, explains the cause in one paragraph and pastes each command with its output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- 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
The pull request names the failed run and quotes the lines that decided the diagnosis. The diff is small and in one place: a post's frontmatter under src/content/posts, a component under src/components or src/layouts, a formatted .astro file, or pnpm-lock.yaml regenerated against the current package.json. The body pastes pnpm run lint, pnpm run format:check and pnpm run build with their output, the last ending in Pagefind's index summary.
The repository's ci.yml runs on the pull request with the same three steps and the same three-minute limit, which is the check that matters: the agent reran them in a sandbox, and the runner reruns them where they failed. When the cause was the timeout, the pull request contains no code change and a paragraph with the step timings, so the decision to raise the budget or trim the build stays with a person.
A reviewer reads the cause against the quoted log, checks that no rule or schema was relaxed (the eslint.config.js, .prettierrc, tsconfig.json and src/content.config.ts lines of the diff should be empty), and, for a lockfile change, that only the dependency named in package.json moved.
Run it on every failed CI run on a pull request
Add an automation to the Project for this site with the prompt above and a github trigger on workflow_run.failure. The workflow runs on pull requests, so a failing contributor branch starts the run; set branch_patterns to main if you want only the default branch's failures. The trigger appends the run event after the prompt, so the agent reads the run id and branch from it, and runs from forks never fire. max_runs_per_hour caps a day of red pushes.
From your own server instead, a handler for GitHub's workflow_run webhook with conclusion: failure sends POST /o/{org}/sessions with this prompt and the run id in input, the repository in resources, and a request_id that is a UUID v5 of the run id so a redelivery returns the same run. A webhook_url on the key receives run.completed with data.session_url to read the pull request from.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
A static site's build is deterministic until it is not: a different pnpm, a different Node, a lockfile a teammate forgot, a font fetched at build time. Reproducing the runner's failure on a laptop means matching all of that first. In a Rush sandbox the agent pins pnpm@11.3.0 and Node 24 as ci.yml does, runs the three scripts in order, and every command with its output is in the transcript beside the fix.
The site's checks stay the referee. The agent is told not to raise the timeout, relax a rule or loosen the schema, so the pull request is a fix to the content or the code that broke, and the same ci.yml proves it on the pull request. A timeout that is really a growing build gets a written explanation instead of a quiet timeout-minutes: 6.
Frequently asked questions
What if the build hit the three-minute timeout?
The agent says so instead of editing the workflow. It reads the step timings from the log, notes what the build does at the end (Pagefind indexing, Open Graph images through satori and sharp), and leaves raising timeout-minutes or trimming the build as a decision for the pull request's reviewer.
Will it turn off the lint rule that failed?
No. no-console is set to error on purpose and the prompt forbids relaxing rules, adding ignores or loosening the content schema. The fix is in the file ESLint named, and a reviewer can confirm eslint.config.js is untouched.
Why does a post's frontmatter break the whole build?
src/content.config.ts validates every post against its schema when astro build loads the collection, so a missing description or a date that is not a date fails the build with the file name. The fix is the one field in that one post.
Does it work with npm or yarn instead of pnpm?
Yes. The agent reads the lockfile and the workflow's setup steps and uses the package manager they name; the frozen-lockfile step becomes npm ci or yarn install --immutable, and the three scripts are the same.