# Add GitHub Actions CI to a Medusa Monorepo

Yes. An agent writes a workflow for your Medusa monorepo that lints, builds, migrates and seeds a Postgres, boots the backend, builds the storefront, and opens a PR.

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

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

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

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

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

- [Add OpenTelemetry Tracing to a Medusa Backend](https://getrush.ai/run/add-opentelemetry/medusa/)
- [Send an Order Confirmation Email from a Medusa Backend](https://getrush.ai/run/add-order-confirmation-email/medusa/)
- [Add Product Reviews to a Medusa Store](https://getrush.ai/run/add-product-reviews/medusa/)

## The same job on other stacks

- [Set Up GitHub Actions CI for a Next.js App](https://getrush.ai/run/add-github-actions-ci/nextjs/)
- [Add GitHub Actions CI to a Phoenix App](https://getrush.ai/run/add-github-actions-ci/phoenix/)
- [Set Up GitHub Actions CI for a Phoenix LiveView App](https://getrush.ai/run/add-github-actions-ci/phoenix-liveview/)

## 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/)
