What the agent does
The agent reads how the project is laid out before it runs anything. In an app like strapi/LaunchPad, the backend is the strapi/ folder with its own package.json and yarn.lock; the root and each of the four front ends have theirs, and AGENTS.md says this is not a Yarn workspace. Yarn is 4.5.0 through the root packageManager field. Three packages are pinned to one exact version, @strapi/strapi, @strapi/plugin-users-permissions and @strapi/plugin-cloud, and must move together. @strapi/plugin-seo has its own caret range and its own release line, so it is not part of the core bump.
There is no test suite and the only workflow triggers a deploy pipeline on pushes to main, so the agent builds its own baseline. On the untouched branch it installs, copies .env.example to .env, runs yarn build in strapi/, imports the demo data with the repository's seed script and starts the server. It then saves the JSON of a fixed list of requests: the collection and single types under strapi/src/api, in en and fr, including the six whose routes attach a populate middleware. Those saved answers are what the upgrade is judged against.
The upgrade uses Strapi's own tool. From strapi/ the agent runs npx @strapi/upgrade minor, which stays on the current major, rewrites the @strapi/* versions, installs, and applies any code changes that release ships. It keeps the tool's output. It rebuilds, restarts on the same seeded database so Strapi's startup migrations run, repeats the requests and diffs the answers. It regenerates types/generated, which is committed, and checks that the postinstall script, which can rewrite the strapi.uuid field in package.json, left only version lines changed.
It also reads what the new version asks of Node. The app's engines field allows Node 18 through 22 and the README says Node 18 or higher. When this page was written, the locked 5.58.0 asked for Node 20 or later and the registry's latest release asked for Node 22 or later. The agent reads the target's engines from the registry, runs under a Node both sides accept, and if the floor moved it updates the app's engines and the README line and puts that at the top of the pull request, because it is the change that breaks a deploy. better-sqlite3 is a native module pinned at 11.7.0, so it reports whether that still installs cleanly there.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Upgrade Strapi in this repository to the newest release on the current major and open a pull request. The backend is in strapi/ with its own package.json and yarn.lock; read the root package.json, AGENTS.md, README.md, strapi/package.json, strapi/.env.example, every file under strapi/config and the routes and middlewares under strapi/src/api first. Do not touch the front-end folders or their lockfiles. Baseline on the untouched branch: enable Corepack, yarn install at the root and in strapi/, copy strapi/.env.example to strapi/.env, run yarn build in strapi/, import the demo data with the seed script, start the server, and save the JSON answers of GET /api/<plural> for every content type under strapi/src/api in locales en and fr, plus one findOne per collection type. Then stop the server and run npx @strapi/upgrade minor in strapi/, keeping its full output. Read the target version's engines from the registry and compare with this app's engines field and the README's Node requirement; if the minimum rose, update both and say so first in the pull request. Rebuild, start on the same database, repeat every request and diff against the baseline. Regenerate the committed types with yarn strapi ts:generate-types. Check git diff on strapi/package.json: only version lines and engines may change, not the strapi.uuid field. Do not upgrade @strapi/plugin-seo or any other dependency in the same pull request. If the build fails or an answer differs, find the cause in the release notes between the two versions, fix what belongs in this repository, and list anything left. If the app is already on the newest release, end with one line saying so and open nothing. In the pull request give the versions before and after, the upgrade tool's output, the build result and a table of the requests compared.",
"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 changes strapi/package.json and strapi/yarn.lock, the generated type files if the schema typings moved, any file the upgrade tool's code changes touched, and the Node requirement when it had to rise. Nothing under next/, astro/, nuxt/ or tanstack/ is in the diff. The description gives the version before and after, the upgrade tool's output, the result of yarn build, and a table with one row per request: identical, or the fields that differ.
A difference is not hidden. If a response gains a field, loses one or reorders a populated relation, the row names the path and the release note that explains it, and says whether a front end reads that field. The four front ends call the API through @strapi/client, so a changed response shape is their problem too, and the pull request says which pages to look at instead of editing them.
A reviewer checks that the three pinned Strapi packages show the same version, that the lockfile diff is confined to Strapi and what it depends on, and that strapi.uuid is unchanged. The comparison runs against the demo export on SQLite in the agent's sandbox. Your production database is migrated by Strapi when the new version first starts there, so take an export or a database backup before the deploy that follows the merge.
Run it on every Monday morning
In the Project that holds the repository, create an automation with a schedule trigger whose cron is 0 9 * * 1 in your timezone and this page's request as its prompt. The request already ends quietly when there is nothing to upgrade, so a week without a release opens no pull request. The automation runs as the member who last edited it and has its own max runs per hour.
Keep major versions out of the schedule. npx @strapi/upgrade major changes plugin APIs and data handling, and deserves a run you start by hand with a prompt that names the migration guide, on a branch you expect to keep open for a while. For an agency with one Strapi backend per client, send this body once per repository to POST /o/{org}/sessions with a request_id that is a UUID v5 of the repository's full name and the ISO week, so a script that runs twice in a week returns the runs it already started.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A Strapi upgrade is usually one command, and that is why it gets merged without a second look. The command changes versions; it does not tell you whether /api/pages?locale=fr still returns the same tree, whether the admin panel still builds with your src/admin customisations, or whether the new release dropped the Node version your host runs. Checking those by hand means seeding a database, starting the server twice and comparing JSON, which nobody does for a minor bump. The agent does it every time in its own sandbox and keeps both sets of answers, so the pull request carries a comparison and not a version number.
It also happens without a developer's machine. The run installs with the repository's Yarn version on a clean checkout, so a stale node_modules or a local .env cannot make the upgrade look healthier than it is. Every command and its output stays in the session's transcript, and when the comparison turns up a difference you can send a follow-up to the same session, which wakes the sandbox with the upgraded app and its database still in place.
Frequently asked questions
Does it use Strapi's upgrade tool or edit package.json by hand?
The tool. npx @strapi/upgrade moves every core @strapi/* package to one version and applies the code changes a release ships with, which a manual edit would miss. The agent keeps its output in the pull request. It edits package.json by hand only for the engines field.
Will it take us from Strapi 4 to Strapi 5?
Not with this request, which says to stay on the current major. A major upgrade changes the content API's response format and the plugin interfaces, and is better started on purpose with a prompt that asks for npx @strapi/upgrade major and a list of every front-end call that reads the old shape.
Does the upgrade touch my production data?
No. The run works on a clone in its sandbox with the demo export, or whatever seed your repository provides, on a local SQLite file. Strapi applies its own database changes when the upgraded code first starts against a real database, which happens at your deploy and not in the run.
What about marketplace plugins and my own plugins?
The request leaves them at their versions so the pull request has one cause for any difference. The agent does check that they still load: a plugin that fails to register shows up in the build or at startup, and the pull request names it with the error. Upgrading that plugin is then a second, small run.
We deploy with Docker. Does it update the image's Node version?
If the Node floor moved and your repository has a Dockerfile or a CI file that names a Node version, the agent lists each place and updates the ones in the repository. It does not build the image, because the sandbox has no Docker unless the agent installs it, and the request does not ask for that.