What the agent does
For a site built from gatsbyjs/gatsby-starter-blog, the agent reads package.json first. It lists gatsby ^5.14.6 and ten official plugins and transformers: gatsby-plugin-feed, -image, -manifest and -sharp, gatsby-remark-images, -prismjs and -responsive-iframe, gatsby-source-filesystem, and gatsby-transformer-remark and -sharp, with React ^18.1.0 and prismjs ^1.30.0. package-lock.json resolves gatsby to 5.16.1, React to 18.2.0 and sharp to 0.32.6. There is no engines field, so the agent uses a current Node LTS and records which one in the pull request.
Gatsby's own plugins are released together and each declares a peer range on gatsby, so the agent upgrades them as one set rather than one at a time: npm install gatsby@latest with every gatsby-* package at the release that matches, then npm update for the rest. A plugin that would pull in a different major of gatsby, or a peer warning from npm, is treated as a reason to hold that plugin back. React stays on 18 unless the new Gatsby release lists React 19 as supported in its peer range.
This starter has no tests: its test script prints Write tests and exits 1. So the agent's check is the build and what the build produces. It runs npm run build (gatsby build), which runs the GraphQL page queries in gatsby-node.js, creates a page for each of the three Markdown posts in content/blog through createPages, processes images with sharp, highlights code with Prism and writes /rss.xml through the feed query in gatsby-config.js. It then runs gatsby serve and requests the home page, each post, /rss.xml and the web manifest, and checks that each answers 200 and that the feed lists all three posts.
When the build fails or a page comes back wrong, the agent returns half the changed packages to their old versions and builds again until it finds the package responsible. A gatsby-plugin-sharp or sharp release that will not install its native binary, for example, is put back with the install error. The build is run once more from a clean state with npm run clean and npm ci before the pull request is opened, so the cached .cache and public directories cannot hide a failure.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Upgrade Gatsby and its plugins to the latest compatible versions with npm. Upgrade gatsby and every gatsby-* package together so their peer ranges match, then the remaining dependencies. Keep React on its current major unless the new Gatsby supports a newer one. This project has no test suite, so run npm run build, then gatsby serve, and check that the home page, every post, /rss.xml and the manifest load and that the feed lists every post. Leave out any upgrade that breaks the build or those checks and say why with the error. Finish with npm run clean, npm ci and npm run build. Open a pull request with one line per bump.",
"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.prix.dev/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 changes package.json and package-lock.json. The description has one line per package with old and new version, Gatsby and its plugins listed first as a group, then the remaining packages. Under that is each upgrade that was left out with the command that failed (npm ci, gatsby build or the page checks) and the error text, and the Node version the build used. Because the starter has no tests, the description lists the pages and files it checked after the build instead of a test count.
A reviewer runs gatsby develop on the branch and reads one post with an image and a code block, since image processing and Prism highlighting are the parts most likely to change visibly between plugin releases. They also check the deploy preview on whichever host builds the site. If a gatsby-transformer-remark change altered excerpts, the RSS feed's description fields are where it shows.
Run it on every first Monday of the month
A blog does not need weekly dependency churn, and Gatsby's plugins move as a set, so a monthly run is often enough. Schedule a job in the tool you already use for cron work to send POST /o/{org}/sessions with this request and the site's repository, using the month as part of the Idempotency-Key.
Add a webhook to the API key and your endpoint is told when the run finishes. Read the session, take the pull request URL, and send it to whoever edits the site. A package held back this month is tried again next month against the newer release.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
gatsby build is heavy for a small site: it installs sharp's native binary, runs every GraphQL query and writes the whole public directory. Trying several version combinations means repeated clean builds, which is slow on a laptop and leaves .cache in a state that confuses the next local build. In a Rush sandbox the agent has its own disk for those builds, and each command's output is kept in the session.
A site with no tests is the case where a dependency bot is least useful, because its pull request is green whenever npm install succeeds. The agent's run does the checks a person would do, building and loading the pages, and only proposes the upgrades that pass. If you run several Gatsby sites, each one gets its own run at the same time within the key's concurrency limit.
Frequently asked questions
My Gatsby site has no tests. How does the agent know an upgrade works?
It builds the site, serves the output and requests the pages and files the starter produces, checking status codes and the RSS feed's contents. That catches broken queries, failed image processing and missing pages. It does not catch a visual change, which is why the reviewer reads a post on the branch.
Will it move Gatsby to a new major version?
Not unless the prompt asks for it. A Gatsby major usually needs code changes in gatsby-node.js or the config, so the agent stays on Gatsby 5 and mentions a newer major in the pull request if one exists.
Why upgrade the plugins together?
Gatsby's official plugins are published together and each one's peer dependency names a range of gatsby versions. Moving gatsby without its plugins leaves peer warnings or a broken build, so the agent treats them as one unit.
What about third-party plugins?
They are upgraded with the rest, and if one has no release that supports the new Gatsby the agent keeps the current Gatsby and says which plugin is holding it back.