# Add Dependabot to a Koa API

Yes. An agent reads your Koa app's package.json, lockfile, Dockerfile and workflow, writes a grouped dependabot.yml, proves the suite is green, and opens a PR.

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

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

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

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

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

## More Koa jobs

- [Add Graceful Shutdown to a Koa API](https://getrush.ai/run/add-graceful-shutdown/koa/)
- [Add Health Check Endpoints to a Koa API](https://getrush.ai/run/add-health-checks/koa/)
- [Add Input Validation to a Koa App](https://getrush.ai/run/add-input-validation/koa/)

## The same job on other stacks

- [Add Dependabot to a Lit Component Project](https://getrush.ai/run/add-dependabot/lit/)
- [Set Up Dependabot for a Maven Project](https://getrush.ai/run/add-dependabot/maven/)
- [Add Dependabot to a Medusa Monorepo](https://getrush.ai/run/add-dependabot/medusa/)

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