What the agent does
The agent reads how the repository is installed and run before it writes a workflow, because a Medusa monorepo has two apps with different needs. In a repository laid out like medusajs/dtc-starter, the root package.json pins packageManager to pnpm@10.11.1, requires Node 22.23.4 or later, and runs everything through Turborepo: pnpm build, pnpm lint and pnpm test fan out to apps/** as pnpm-workspace.yaml declares, with .medusa/ excluded and @medusajs/telemetry the only package allowed to run build scripts. turbo.json makes build depend on upstream builds and caches dist/** and .next/**. eslint.config.ts at the root loads @medusajs/eslint-plugin. The only workflow, .github/workflows/update.yaml, runs on workflow_dispatch and a medusa-release-published dispatch to open upgrade pull requests with medusa-update-action; nothing runs on a pull request, and AGENTS.md notes the storefront has no test suite and the backend defines no plain test script.
apps/backend/package.json is @dtc/backend on @medusajs/medusa, @medusajs/framework and @medusajs/cli 2.22.1, with build as medusa build, lint as medusa lint, and three Jest scripts keyed by TEST_TYPE that match no files yet, since integration-tests/ holds only setup.js. medusa-config.ts reads DATABASE_URL, three CORS lists and the JWT and cookie secrets, all listed in .env.template, and AGENTS.md says medusa db:migrate runs the migrations and then src/migration-scripts/, where initial-data-seed.ts creates the store, a Europe region, shipping options, a publishable API key and products. apps/storefront/package.json is @dtc/storefront on Next 16.3.8, builds with next build, and its next.config.js calls check-env-variables.js, which exits when NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY is unset. README.md asks for PostgreSQL 15 or later.
The agent writes .github/workflows/ci.yml with two jobs on pull requests and pushes to main, both installing with pnpm/action-setup reading the packageManager field, actions/setup-node on Node 22 with the pnpm cache, and pnpm install --frozen-lockfile. The lint job runs pnpm lint through Turborepo so both apps are covered. The backend job adds a postgres:15 service, exports DATABASE_URL and the CORS and secret values from .env.template, runs pnpm --filter @dtc/backend build, pnpm --filter @dtc/backend exec medusa db:migrate, which proves the migrations and the seed script, then starts medusa start in the background and waits for GET /health on port 9000 before killing it. The storefront build runs in that same job after the backend is up: the agent reads the publishable key the seed created back out of the database with psql, exports it as NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY with NEXT_PUBLIC_MEDUSA_BACKEND_URL set to the local server, and runs pnpm --filter @dtc/storefront build, so the storefront is built against the API it will talk to rather than a placeholder key that passes the env check and fails the first fetch.
Each step is run in the agent's own sandbox first, with Postgres installed there and pnpm 10.11.1 on Node 22: install, lint, build, migrate, the health probe, the key lookup and the storefront build, in that order, with the time each took written down for the job's timeout-minutes. A concurrency group per ref cancels superseded runs, permissions is contents: read, and the test:* scripts are left out of the workflow with a comment naming them, since there is nothing for them to run yet.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add GitHub Actions CI to this Medusa monorepo. Read package.json, pnpm-workspace.yaml, turbo.json, .npmrc, eslint.config.ts, AGENTS.md, README.md, apps/backend/package.json, apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/jest.config.js, the files under apps/backend/src/migration-scripts, apps/storefront/package.json, apps/storefront/next.config.js, apps/storefront/check-env-variables.js, apps/storefront/.env.template and .github/workflows/update.yaml first. Write .github/workflows/ci.yml with a lint job that runs pnpm lint through turbo, and a backend job with a postgres:15 service that exports the values from apps/backend/.env.template, builds the backend, runs medusa db:migrate, starts medusa start in the background, waits for GET /health on port 9000, reads the publishable API key the seed created from the database with psql, and builds the storefront with that key and the local backend URL. Both jobs run on pull requests and pushes to main, install pnpm from the packageManager field with the pnpm cache on Node 22 and pnpm install --frozen-lockfile, with contents: read permissions, a concurrency group per ref and timeouts. Leave the test scripts out with a comment, since no test files exist. Install Postgres and pnpm in your sandbox, run every step in order, and open a pull request with the output of each. Do not change update.yaml, any package.json or any source file.",
"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 adds .github/workflows/ci.yml and nothing else. Its description pastes the result of each sandbox step in order: pnpm lint across both apps, the medusa build output, the migration list and the seed's log lines from medusa db:migrate, the /health response, the key lookup, and the next build route table from the storefront, with the time each took and the timeouts chosen from them.
Both jobs run on the pull request itself, so the first green check is on the change that added it. update.yaml keeps opening Medusa upgrade pull requests, and from now on each of those is built, migrated and booted before anyone reads it.
Before merging, a reviewer decides whether the storefront build belongs in the backend job or in one of its own with a placeholder key, whether medusa db:migrate should run against a database kept between jobs, and when the empty test:* scripts get files worth adding to the workflow.
Run it on every new repository
A team that runs several Medusa projects sends this body once per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads its own repository: a backend-only project gets no storefront step, one on Yarn gets the Yarn cache, and one with files under integration-tests/http/ gets test:integration:http as a step with the same Postgres service.
Once the workflow is merged, an automation on the Project with a github trigger on workflow_run.failure and the prompt "if the failed workflow is ci, read its log, name the step and the file that failed and comment on the pull request with the fix" turns a red run into a specific comment. The trigger adds the event after the prompt, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A first workflow for a monorepo is easy to write and easy to get wrong where only a runner shows it: a package manager that does not match the lockfile, a build script that fails without an environment variable, a seed that needs a database the job never started, a storefront whose env check exits before next build begins. The agent runs each step in its own sandbox against a Postgres it installed there, so the workflow it writes has already passed once.
The output of every step stays with the run and is pasted into the pull request, so the reviewer reads what the build, the migration and the health probe actually printed. The same request runs for every Medusa repository a team owns at once.
Frequently asked questions
There are no tests. What does the workflow check?
That the code lints under @medusajs/eslint-plugin, that medusa build compiles the backend and admin, that every migration and the initial data seed apply to a fresh Postgres 15, that the server boots and answers /health, and that the storefront builds against that server with a real publishable key. The three test:* scripts are named in a comment for when test files exist.
Why read the publishable key from the database instead of a placeholder?
check-env-variables.js only checks the variable is set, so a placeholder passes it and the build then calls the backend with a key it rejects. The seed in src/migration-scripts/initial-data-seed.ts creates a real key linked to the sales channel, and the job reads it with psql after medusa db:migrate so the storefront build is a true one.
Does this interfere with the Medusa upgrade workflow?
No. update.yaml keeps its dispatch triggers and opens pull requests as before; the new workflow runs on those pull requests, so an upgrade that breaks the build or a migration is red before merge rather than after.
Why Node 22 and pnpm from `packageManager`?
engines.node requires 22.23.4 or later and packageManager pins pnpm@10.11.1; pnpm/action-setup reads that field so the workflow and the lockfile never disagree, and AGENTS.md warns against assuming the package manager, which is why the workflow reads it rather than naming it twice.
More Medusa jobs
The same job on other stacks
- Set Up GitHub Actions CI for a Next.js App (Next.js)
- Add GitHub Actions CI to a Phoenix App (Phoenix)
- Set Up GitHub Actions CI for a Phoenix LiveView App (Phoenix LiveView)