# Fix a Failing CI Build for an Astro Site

Yes. An agent reads the failed step's log, reruns lint, format check and the full astro build with your pnpm and Node versions, fixes the cause and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-failing-ci/astro/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

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.phoenix.so/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

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.

## 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.

## More Astro jobs

- [Turn Sentry Errors Into Fix Pull Requests for an Astro Site](https://getrush.ai/run/fix-sentry-errors/astro/)
- [Fix a Failed Vercel Deployment of an Astro Site](https://getrush.ai/run/fix-vercel-build-failures/astro/)
- [Find Why a Vercel Deploy Broke an Astro Site](https://getrush.ai/run/investigate-vercel-deploy/astro/)

## The same job on other stacks

- [Fix Failing GitHub Actions Checks in a Django App](https://getrush.ai/run/fix-failing-ci/django/)
- [Fix a Failing CI Build in a .NET Project](https://getrush.ai/run/fix-failing-ci/dotnet/)
- [Fix a Failing CI Run for an Electron App](https://getrush.ai/run/fix-failing-ci/electron/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
