What the agent does
The agent starts by reading what Dependabot would have to update, because a grouped configuration written without that is a guess. In a Koa API laid out like javieraviles/node-typescript-koa-rest, package.json names koa, @koa/router, @koa/cors, koa-bodyparser, koa-helmet, koa-jwt and koa-swagger-decorator on the web side, typeorm, pg, reflect-metadata and class-validator on the data side, and winston, cron and dotenv beside them, all on caret ranges. The dev side has jest, ts-jest, typescript, eslint, the two @typescript-eslint packages, ts-node, nodemon and a row of @types packages, one of which, @types/koa, is pinned exactly while koa itself is not. engines asks for Node 14 and npm 6, and package-lock.json is a lockfileVersion 1 file that Dependabot will regenerate with its own npm on every update. There is no .github/dependabot.yml; the only file under .github is workflows/ci.yml.
That workflow is the second thing the agent reads, because a github-actions entry is only useful for references Dependabot can bump. ci.yml runs on ubuntu-16.04, a runner label GitHub no longer provides, and pins actions/checkout@master, actions/heroku@master, actions/setup-node@v1 and actions/setup-python@v1. Dependabot updates a version tag, so a @master reference has nothing to update; the agent pins the two branch references to a release tag in the same pull request and says so, and leaves the v1 tags for Dependabot's first run. It also reads Dockerfile (FROM node:14-alpine) and docker-compose.yml (postgres:10-alpine and adminer), and the jest block in package.json, which matches tests/**/*.ts through ts-jest.
Then it writes .github/dependabot.yml. The npm entry on / runs weekly and groups what should land together: a koa group for koa, @koa/* and koa-*, a typeorm group for typeorm, pg, reflect-metadata and class-validator, a lint group for eslint and @typescript-eslint/*, a test group for jest, ts-jest and @types/jest, and a types group for the remaining @types/*. It adds an ignore rule for major updates of typeorm: the app is on the 0.2 line, and the 0.3 line changed findOne's signature and deprecated createConnection and getManager, which src/server.ts and src/controller/user.ts call, so that upgrade is a code change and not a bot pull request. A github-actions entry on / covers the workflow, and a docker entry on / covers the node:14-alpine base image. The agent checks the file against the dependabot-2.0 JSON schema from SchemaStore before committing it, because a misspelled key in this file is ignored rather than rejected.
Last, it proves the baseline is green so the first Dependabot pull request has something to compare against: npm ci, then npm run lint, which runs tsc --noEmit and ESLint, then npm test, which runs the controller and entity tests under Jest with TypeORM and class-validator mocked, so no Postgres is needed. The output of all three is pasted into the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Dependabot to this Koa API. Read package.json, package-lock.json, .github/workflows/ci.yml, Dockerfile, docker-compose.yml, tsconfig.json and the tests directory first. Write .github/dependabot.yml with a weekly npm entry on / that groups Koa packages, the TypeORM and database packages, lint packages, test packages and @types packages, and ignores major updates of typeorm because the app uses the 0.2 API. Add a github-actions entry and a docker entry for the Dockerfile base image. In ci.yml, pin any action referenced by a branch name to a release tag so Dependabot can track it, and say which ones you changed. Validate the file against the dependabot-2.0 JSON schema. Run npm ci, npm run lint and npm test, and open a pull request with the file, the ci.yml change, the schema check and the test output. Do not upgrade any dependency yourself.",
"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/dependabot.yml and changes .github/workflows/ci.yml where an action was referenced by branch. Its description lists each group and the packages it matches, explains the typeorm ignore rule with the two call sites that depend on the 0.2 API, names the actions it pinned, and pastes the schema check and the npm run lint and npm test output.
The existing CI workflow runs on the pull request as it always has. Once the file is merged, Dependabot opens its first pull requests on the next weekly slot, one per group, each with a lockfile diff a reviewer can read.
Before merging, a reviewer decides whether the weekly interval and the default open pull request limit suit the repository, whether @types/koa should move to a caret range so the types group can carry it, and whether the ubuntu-16.04 runner label should be replaced in the same change or in its own. The agent names that label in the description and leaves the choice to the reviewer.
Run it on every Node repository without Dependabot
A team with many Node services sends this body once per repository to POST /o/{org}/sessions, each with its own 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 opening a second pull request. Each run reads its own manifest: a service on pnpm gets the npm entry pointed at its pnpm-lock.yaml directory, a monorepo gets one entry per package directory, and a repository that already has dependabot.yml gets a comment on what the file lacks and no pull request.
The key's webhook_url reports each run.completed with the pull request in result, and a run past the key's max_concurrent limit answers 202 with status: "queued" and starts when a slot frees, so a batch of repositories needs no retry loop.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A Dependabot file is short, and the mistakes in it are quiet: a group pattern that misses @koa/router because it only matched koa-*, a branch-pinned action that never gets a pull request, a major TypeORM update that fails CI for reasons that have nothing to do with the dependency. The agent reads the manifest, the lockfile format, the workflow and the Dockerfile before it writes a line, and validates the result against the schema in its own sandbox.
The schema check, npm ci, npm run lint and npm test all stay with the run, and the pull request quotes them, so a reviewer reads a file that was checked against a green baseline rather than one that looks right. Twenty repositories get the same treatment at once, each in its own sandbox with its own pull request.
Frequently asked questions
Why ignore TypeORM's major version instead of letting Dependabot try it?
Because the pull request would fail for reasons a bot cannot fix. The app calls createConnection in src/server.ts and getManager and findOne(id) in src/controller/user.ts, all 0.2-line APIs that the 0.3 line changed or deprecated. An ignore rule for version-update:semver-major on typeorm keeps minor and patch updates flowing and leaves the major for a deliberate change.
Will Dependabot upgrade the lockfile to a newer format?
The agent does not touch it. package-lock.json is lockfileVersion 1, and Dependabot regenerates the lockfile with its own npm when it updates a package, so the pull request tells the reviewer to read the first Dependabot diff for the format that comes back. Moving to a newer lockfile format on purpose is a separate change made by running a newer npm once.
Why does the pull request touch ci.yml at all?
Because actions/checkout@master and actions/heroku@master are branch references, and Dependabot only updates version tags. Pinning them to a release tag gives the github-actions entry something to track. The @v1 references on setup-node and setup-python are left for Dependabot's first run, since updating them is exactly its job.
Does the run need a database?
No. The Jest tests in tests/controller/user.test.ts mock typeorm and class-validator, so npm test runs without Postgres, and npm run lint only type-checks and lints. The agent never starts the server or the docker-compose.yml services for this job.