What the agent does
The agent reads where the manifests are and how versions are pinned before it writes a config, because a Dependabot file that names the wrong directory or the wrong strategy opens no pull requests and nobody notices. In a repository laid out like sequelize/express-example, the root holds readme.md, license, .editorconfig and .gitattributes, and the app lives one level down in express-main-example/, whose package.json depends on express at ^4.17.1, sequelize at ^6.3.3, sqlite3 at ^5.0.0 and body-parser at ^1.19.0, with engines.node at >=10 and two scripts, start and setup-example-db. Its .npmrc says package-lock=false, and no lockfile is committed. There is no .github directory, so no workflows and no existing Dependabot config. index.js checks the database connection with sequelize.authenticate() and starts Express on port 8080; sequelize/index.js opens a SQLite file under sqlite-example-database/ with logQueryParameters and benchmark on and registers the user, instrument and orchestra models; express/app.js mounts the three route modules under /api/<name> through a wrapper that forwards async errors to next. The last commit on the default branch is from March 2022, so every dependency is behind.
The config goes at .github/dependabot.yml, the only path Dependabot reads, with version: 2 and one npm entry whose directory is /express-main-example, because Dependabot looks for the manifest in the directory the entry names and not below it. The schedule is weekly on a named day so the pull requests arrive together, and open-pull-requests-limit is kept small for a repository with four dependencies. No github-actions entry is added, since there is no workflow for it to update, and the pull request says that one line is all it takes when a workflow appears.
The strategy is the part that matters here. Without a lockfile there is no resolved version for Dependabot to bump, only the ranges in package.json, and GitHub's options reference says increase-if-necessary leaves a requirement alone when it already allows the new release, so a ^4.17.1 would sit unchanged through every 4.x release and only move for a major. The agent sets versioning-strategy: increase, documented as always raising the minimum version requirement to match the new version, so each release inside the range still produces a pull request that moves the floor, which is what a repository without a lockfile needs to see any change at all. A groups block puts minor and patch updates into one pull request a week and leaves majors, such as express 5 or body-parser 2, as their own, since each of those is a review with code changes behind it.
The agent checks its work in its sandbox with npm install under a Node that satisfies engines, runs npm run setup-example-db and starts index.js to confirm the app still boots before any dependency moves, so the first Dependabot pull request has a known-good baseline to compare against. It does not add a lockfile, because .npmrc disables one on purpose, and it does not add a workflow, which is a separate decision the pull request names.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Dependabot to this repository. Read the root directory, express-main-example/package.json, express-main-example/.npmrc, index.js, express/app.js and sequelize/index.js first, and note which directory holds the manifest and whether a lockfile is committed. Write .github/dependabot.yml with version 2 and an npm entry whose directory is the one with package.json, a weekly schedule on a named day, a small open-pull-requests-limit, versioning-strategy set to increase because there is no lockfile and the ranges use carets, and a groups block that combines minor and patch updates into one pull request while leaving major updates separate. Add a github-actions entry only if a workflow exists. Install with a Node that satisfies engines, run the setup-example-db script and start the app in the sandbox to confirm it boots before any update, and open a pull request that explains the directory and the strategy choice. Do not add a lockfile or a workflow.",
"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 one file, .github/dependabot.yml, and nothing else. Its description explains the two choices a reader would otherwise ask about: why directory is /express-main-example and not /, and why versioning-strategy is increase for a manifest with caret ranges and no lockfile, with the sentence from GitHub's options reference that each choice rests on. It also pastes the sandbox output of npm install, the database setup script and the app's startup lines as the baseline.
Nothing runs on the pull request because the repository has no workflows. Once it merges, Dependabot opens its first pull requests on the next scheduled day: one grouped pull request for minor and patch releases of the four dependencies, and one each for any major, which for a 2022 manifest will include express 5 and body-parser 2.
Before merging, a reviewer decides whether to add a workflow that runs npm install and starts the app, so Dependabot's pull requests carry a check, and whether sqlite3 majors should be ignored until the Node floor in engines is raised, since its native build is the dependency most likely to drop an old Node.
Run it on every new repository
An organisation can send this body once per repository from its own server when a repository is created, each a POST /o/{org}/sessions 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. Each run reads its own layout: a repository with package.json at the root gets directory: /, one with a lockfile gets the default strategy because the lock gives Dependabot a resolved version to bump, a monorepo gets one directories list with a glob, and one with workflows gets the github-actions entry.
After the config merges, the pull requests it produces are the next event. An automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request is from Dependabot, install the dependencies, start the app and comment with whether it still boots and what changed in the changelog of the updated package" gives each one a comment to read before merging. Automation runs are read-only, so the comment is all it posts, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Dependabot is one YAML file, and the two fields most repositories get wrong are the directory and the strategy: a config at the root of a repository whose manifest is in a subdirectory finds nothing, and the default strategy on caret ranges with no lockfile stays quiet until a major. The agent reads the layout and the .npmrc first and writes the config to the repository it is in, with the reasoning in the pull request.
The install and startup output stay with the run and are pasted into the pull request, so the baseline the first Dependabot pull request is judged against is recorded. Several repositories get a config at once, each with its own directory, strategy and ecosystems.
Frequently asked questions
Why does the directory point into a subfolder?
Because Dependabot reads the manifest in the directory the entry names, and this repository keeps package.json in express-main-example/ with only a readme and a license at the root. An entry with directory: / would find no manifest and open nothing.
What does increase change?
With .npmrc disabling the lockfile, the only thing Dependabot can update is the range in package.json. GitHub's reference says increase always raises the minimum requirement to the new version, so a caret range moves up to each new release, where the default would leave the range alone because it already allows it.
Will it open one pull request per package?
For minor and patch releases, no: the groups block combines them into one pull request per week. A major release of any package gets its own pull request, because express 5 or body-parser 2 each need code read alongside them.
Should it add a lockfile too?
The agent does not, because .npmrc turns lockfiles off deliberately and that is a decision for the team. The pull request says that committing one would let Dependabot use its default strategy and give every update a resolved version.
More Sequelize jobs
The same job on other stacks
- Add Dependabot to a Socket.IO App (Socket.IO)
- Add Dependabot to a SolidJS App (SolidJS)
- Set Up Dependabot for a Streamlit App (Streamlit)