What the agent does
The agent reads how the project is installed and run before it writes a workflow, because in a repository like DomenicoColandrea86/react-vite-typescript-boilerplate most of the answers are in package.json. The preinstall script runs npx only-allow pnpm, postinstall runs git config core.hooksPath ./git-hooks, and every script goes through Nx: test is nx exec -- vitest, build:app is nx exec -- tsc && vite build, lint is nx exec -- eslint --fix --color .. pnpm-lock.yaml starts with lockfileVersion: '6.0', the format pnpm 8 writes; there is no packageManager field and no workflow, and .nvmrc says v18.17.0. Two packages are declared as regular dependencies that only make sense on one machine, @esbuild/linux-arm64 and @nrwl/nx-linux-arm64-gnu, which the docker/Dockerfile also installs globally; the install still passes on an x64 sandbox, so the agent notes them and moves on.
Then it runs the scripts the way a runner would, and two of them do not survive a fresh clone. vite.config.ts sets setupFiles: '.vitest/setup', but .gitignore lists /.vitest, so the file that imports the jest-dom matchers was never committed and vitest run fails every suite with Failed to load url .../.vitest/setup. The only test, src/app/App.test.tsx, wraps an it inside a test callback, so once a setup file exists it reports one passing test that asserts nothing. Rewriting it as a describe block shows the assertion itself is wrong: getByText(/Vite + React/i) is a regular expression in which + repeats the space before it, so it never matches the literal Vite + React heading. pnpm build:app (tsc then vite build) and pnpm exec eslint . both pass as committed.
So the pull request carries a small test fix beside the workflow, because a CI that runs vitest must have something real to run. The agent adds .vitest/setup.ts with import '@testing-library/jest-dom', removes /.vitest from .gitignore, and rewrites the test as describe and it with getByRole('heading', { name: 'Vite + React' }), which passes in its sandbox. It also checks what the git hooks would have caught: git-hooks/pre-commit lints only staged files matching .ts$, so .tsx files, including that test, were never linted on commit.
The workflow it writes, .github/workflows/ci.yml, runs on push and pull_request, checks out with actions/checkout, installs pnpm with pnpm/action-setup pinned to major version 8 to match the lockfile, then actions/setup-node with node-version-file: .nvmrc and cache: pnpm, so the store is cached under the lockfile's hash. Steps run pnpm install --frozen-lockfile, pnpm exec eslint . (not the lint script, whose --fix would rewrite files on the runner), pnpm exec vitest run (not pnpm test, which starts vitest in watch mode), and pnpm build:app. The agent confirms the frozen install leaves pnpm-lock.yaml untouched with pnpm 8, and that pnpm 9 also installs from this v6 lockfile without rewriting it, so the pin is a choice the reviewer can change.
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 pnpm project. Read package.json, pnpm-lock.yaml (its lockfileVersion), .nvmrc, .gitignore, vite.config.ts, src/app/App.test.tsx, git-hooks/pre-commit and docker/Dockerfile first, then run pnpm install --frozen-lockfile, eslint, vitest run and the build in your sandbox and note what fails on a fresh clone. Write .github/workflows/ci.yml that runs on push and pull_request, installs pnpm with pnpm/action-setup at the major version that wrote the lockfile, uses actions/setup-node with node-version-file .nvmrc and cache pnpm, and runs the frozen install, eslint without --fix, vitest run and the build. If the test suite cannot run as committed, make the smallest fix that lets it run and assert something real, and say exactly what you changed. Open a pull request that pastes the output of each step from your sandbox.",
"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
What comes back is a pull request with .github/workflows/ci.yml, a committed .vitest/setup.ts, a one-line change to .gitignore, and a rewritten src/app/App.test.tsx. The description pastes the sandbox output of pnpm install --frozen-lockfile, pnpm exec eslint ., pnpm exec vitest run and pnpm build:app, and quotes the two failures it hit on the untouched clone: the missing setup file and the nested it that passed without asserting.
The description also lists what it saw and did not change: the --fix in the lint script, the two linux-arm64 packages in dependencies, the pre-commit hook's .ts$ filter that skips .tsx files, and the node:18-alpine base image in docker/Dockerfile. Each is a line a reviewer can turn into a follow-up or dismiss.
Before merging, a reviewer decides whether to pin pnpm at 8 or move the lockfile to a newer pnpm in the same pull request, checks that the Node version in .nvmrc is the one the team wants the runner on, and watches the workflow's first run on the pull request itself, which is the first time the test suite runs anywhere but a laptop.
Run it on every repository without a workflow
A team with several pnpm projects sends one POST /o/{org}/sessions per repository from a terminal or a script, with this prompt and the 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. GET /o/{org}/github lists the repositories the Rush GitHub App reaches, so the script starts a run only where pnpm-lock.yaml exists and .github/workflows/ does not.
Each run opens at most one pull request on its own branch. A key starts at most max_concurrent runs at once (default 4); a run past that answers 202 with status: "queued" and starts as a slot frees, so the script needs no retry loop.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The workflow itself is a dozen lines; what takes the time is finding out that the test suite cannot run from a clean checkout, that the one test passes without asserting, and that the lint script rewrites files. Those only show up on a machine that is not the author's. The agent's sandbox is exactly that machine: it installs from the lockfile with the pnpm version that wrote it, runs each script, and writes the workflow around what actually passed rather than what the scripts are named.
Every command and its output stays on the run, so a reviewer reads the failing vitest output from the untouched clone next to the passing one after the fix, without checking anything out. Several pnpm repositories can get a workflow at once, each in its own sandbox, and a script the agent could not make pass is reported in the pull request, not quietly left out of the YAML.
Frequently asked questions
Why pin pnpm to version 8?
Because pnpm-lock.yaml says lockfileVersion: '6.0', which pnpm 8 writes, and there is no packageManager field to read a version from. pnpm/action-setup with version: 8 installs the same major that produced the lockfile. The agent also ran pnpm@9 install --frozen-lockfile against the same file and it installed without rewriting the lockfile, so moving the pin is a reviewer's choice, not a blocker.
Why does the workflow not run pnpm test or pnpm lint?
test is nx exec -- vitest, which starts vitest in watch mode and would hang a runner, so the step runs pnpm exec vitest run. lint is nx exec -- eslint --fix --color ., which rewrites files; a lint step that fixes things on the runner never fails, so the step runs pnpm exec eslint . instead.
Why does the pull request touch a test file at all?
Because the suite could not run: vite.config.ts points setupFiles at .vitest/setup, and .gitignore excludes /.vitest, so a fresh clone fails every suite with Failed to load url. Once a setup file exists, the only test wraps it inside test and passes without running its assertion, and the assertion's regular expression /Vite + React/i cannot match the literal heading. The agent commits the setup file and rewrites that one test; nothing else under src/ changes.
Does the install work on an x64 runner with arm64 packages in dependencies?
Yes. @esbuild/linux-arm64 and @nrwl/nx-linux-arm64-gnu are listed under dependencies, which is unusual, but pnpm install --frozen-lockfile completed on the agent's x64 sandbox and the build passed. The agent names them in the pull request so the team can move them out of dependencies; the workflow does not depend on it.
Will the cache key change when dependencies change?
Yes. actions/setup-node with cache: pnpm keys the pnpm store on the hash of pnpm-lock.yaml, so a lockfile change produces a fresh cache entry and an unchanged lockfile restores the previous one. It needs pnpm on the PATH before it runs, which is why pnpm/action-setup comes first in the workflow.
More pnpm jobs
The same job on other stacks
- Set Up GitHub Actions CI for a Pulumi Project (Pulumi)
- Set Up GitHub Actions CI for a React Native App (React Native)
- Set Up GitHub Actions CI for a React Router App (React Router)
- Add GitHub Actions CI to a Rocket App (Rocket)
- Add GitHub Actions CI to a Sequelize App (Sequelize)