All jobs

Upgrade Astro Dependencies Every Week

Yes. Once a week an agent bumps your Astro blog's pnpm packages, runs the lint, format and astro check plus build steps CI runs, drops what breaks, and opens one PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

An Astro blog built on satnaing/astro-paper is a single pnpm package, and the agent reads how it is pinned before it bumps anything. package.json asks for Node >=22.12.0 in engines, pnpm-lock.yaml is lockfileVersion: '9.0', and pnpm-workspace.yaml holds only an allowBuilds block that lets esbuild and sharp run their install scripts, which a bumped sharp still needs. .github/workflows/ci.yml pins pnpm 11.3.0 through pnpm/action-setup@v4 and Node 24 through actions/setup-node@v4 with the pnpm cache, installs with pnpm install --frozen-lockfile, and runs three steps: pnpm run lint, pnpm run format:check and pnpm run build. The Dockerfile instead enables corepack and pnpm@latest on node:lts, so a lockfile the CI pnpm cannot read breaks the image build as well as CI.

The dependency list is small and mostly on caret ranges: astro ^7.0.3 with @astrojs/mdx ^7.0.0, @astrojs/rss ^4.0.19, @astrojs/sitemap ^3.7.3 and @astrojs/markdown-remark ^7.2.0, tailwindcss ^4.3.2 with @tailwindcss/vite and @tailwindcss/typography, satori ^0.26.0 and sharp ^0.35.2 for the generated Open Graph images, remark-toc, remark-collapse and rehype-callouts, pagefind ^1.5.2 with @pagefind/default-ui, @shikijs/transformers ^4.3.0, @astrojs/check ^0.9.9, typescript ^6.0.3, and eslint ^10.6.0 with eslint-plugin-astro and @typescript-eslint/parser. Two are exact: prettier 3.9.3 and prettier-plugin-astro 0.14.1, with prettier-plugin-tailwindcss on a caret. The agent moves caret ranges to the latest release that still satisfies them with pnpm update, reads pnpm outdated for what sits beyond a range, keeps the two exact pins unless the prompt says otherwise, and treats astro and @astrojs/mdx as a pair, since the integration's major tracks Astro's. CHANGELOG.md shows the project itself moved from src/data/blog to src/content/posts and from src/config.ts to astro-paper.config.ts at v6.0.0, so a dependency bump must not be mixed with that kind of change, and cz.yaml sets conventional commits, so the pull request is a chore(deps) commit.

There is no test suite; .github/CONTRIBUTING.md says so, and asks reviewers to test by hand. The build is the test. pnpm run build is astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/: astro check type-checks every .astro and .ts file under src, the build renders every post in src/content/posts through the collection schema in src/content.config.ts (a glob loader, pubDatetime as a date, tags defaulting to others, an ogImage that is an image or a string), the src/pages/og.png.ts route and the per-post Open Graph routes render through satori and sharp because dynamicOgImage is on in astro-paper.config.ts, and pagefind indexes dist. astro.config.ts wires remarkToc, remarkCollapse on Table of contents, rehypeCallouts, Shiki with transformerFileName, transformerNotationHighlight, transformerNotationWordHighlight and transformerNotationDiff, the fontProviders.google() font for Google Sans Code, and the svgOptimizer experimental flag, so a Shiki transformer rename, a font provider change or a renamed experimental option surfaces as a build error rather than a test failure. pnpm run lint runs ESLint with no-console as an error over .astro and .ts, and pnpm run format:check runs Prettier with the Astro and Tailwind plugins.

The procedure is baseline, bump, rebuild, bisect. The agent installs with the frozen lockfile and runs the three CI steps once to prove the tree is green before it touches package.json. Then it bumps, reinstalls, and runs them again. When the build fails it reads which package the error names (a satori font-loading error, a Shiki transformer type error, a Tailwind utility the typography plugin no longer knows), pins that one package back to its previous version, rebuilds, and records the error text for the pull request. After a green build it starts pnpm run preview, fetches the index, a post page, a tag page, the archives page, rss.xml, robots.txt and the og.png route, and confirms each answers with a 200 and the expected content type, because a build can succeed while an Open Graph image renders blank.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrade this Astro site's npm dependencies to their latest releases within the ranges in package.json, using pnpm 11.3.0 as .github/workflows/ci.yml does and Node 24. Read package.json, pnpm-workspace.yaml, astro.config.ts, astro-paper.config.ts, src/content.config.ts and ci.yml first. Keep prettier and prettier-plugin-astro at their exact pins, and move astro and @astrojs/mdx together or not at all. Run pnpm install --frozen-lockfile, pnpm run lint, pnpm run format:check and pnpm run build before changing anything for a baseline, then pnpm update, pnpm install, and the same three commands again. For each package whose upgrade fails lint, format or build, pin it back to its previous version, rebuild, and keep the first error line. After a green build, run pnpm run preview and fetch the home page, one post page, one tag page, the archives page, rss.xml, robots.txt and og.png, and confirm each answers 200. Do not change the Dockerfile, the workflow, pnpm-workspace.yaml or any file under src. Open one pull request with a conventional chore(deps) title whose body lists each package with its old and new version, the packages left alone with the error that stopped them, and the output of the three commands.",
  "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

What comes back is a pull request that changes package.json and pnpm-lock.yaml and nothing else. Its body lists each package with its old and new version, then the packages it left alone with the first error line each one produced, then the pnpm run lint, pnpm run format:check and pnpm run build output from the sandbox and the status of each preview request. The ci.yml workflow runs the same three steps on the pull request, since it triggers on opened, edited, synchronize and reopened.

The session read at GET /o/{org}/sessions/{id} names the branch and the pull request URL, and the transcript at GET /o/{org}/sessions/{id}/messages keeps every pnpm command with its output, including the baseline run, each failed build and the pinned-back retry, so a reviewer can see why a package was skipped without rerunning anything.

Before merging, a reviewer checks the skipped list, because a package pinned back this week is the one to look at by hand, reads the Open Graph image the preview produced, and decides whether a major that pnpm outdated reported but the range excluded should be taken on its own branch.

Run it on every Monday morning

Add an automation to the Project with this prompt and a schedule trigger with cron set to the hour you want on Monday, such as 0 7 * * 1, and your IANA timezone; every with 1d is the daily alternative, read in the same timezone. Each firing starts one run in its own sandbox and opens one pull request, so an upgrade that fails leaves last week's branch untouched. Turn the automation off during a release freeze and back on afterwards; turning it back on moves the schedule to its next slot rather than firing the slots it missed.

From your own scheduler instead, send POST /o/{org}/sessions with this body and a request_id that is a UUID v5 of the week number, so a retried job returns the run already started rather than a second one. Give the key a webhook_url and Rush POSTs run.completed, run.failed or run.cancelled when the turn ends, signed per Standard Webhooks, with data.session_url to read for the pull request.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A site with no test suite is the one that most needs the build run before a dependency bump is merged, and that build needs pnpm 11, Node 24, sharp with its native install script allowed, and a Pagefind index, which is more than a laptop with a different Node tends to have. The agent reproduces CI's own environment in its sandbox, runs the three steps CI runs, and adds the preview requests CI does not make.

The result carries its proof: a pull request that lists each bump with the commands that passed after it, and each skipped package with the error that stopped it, with the full transcript on the session. The sandbox parks with node_modules installed when the turn ends, so asking it to take a major on its own branch is a follow-up on the same session rather than a second install.

Frequently asked questions

Will it change the exact-pinned Prettier versions?

No. prettier and prettier-plugin-astro are pinned exactly in package.json, and the prompt says to keep them. A Prettier bump can change formatting output, which would fail pnpm run format:check on every file, so it belongs in its own pull request with pnpm run format run after it.

What happens when Astro ships a new major?

A caret on ^7.0.3 excludes it, so pnpm update leaves it alone and pnpm outdated lists it. The pull request body names it as available but out of range. Ask for it in a follow-up on the session, or on its own run, with @astrojs/mdx moved at the same time.

There are no tests. How does it know an upgrade is safe?

It runs what the repository has: astro check for types, the full astro build with every post, Open Graph image and the Pagefind index, ESLint and the Prettier check, then a preview server with requests to the main routes. An upgrade that passes all of that and still renders a page wrongly is caught by the reviewer reading the preview output, which the pull request links.

Does it respect the allowBuilds list in pnpm-workspace.yaml?

Yes. pnpm 11 skips the install scripts of packages not listed there, and the file already allows esbuild and sharp. A new transitive dependency that needs a build script makes pnpm install print a warning, which the agent reports rather than silently adding to the list, because the prompt forbids changing that file.

Will it touch the Dockerfile or the pnpm version in CI?

No. The workflow pins pnpm 11.3.0 and Node 24 and the Dockerfile uses corepack, and both are left alone. If a bump needs a newer pnpm to read the lockfile, the build fails in the sandbox with that error, the package is pinned back, and the error is in the pull request for you to decide.

More Astro jobs

The same job on other stacks

Keep reading