All jobs

Add Dependabot to a Poetry Project

Yes. An agent adds a dependabot.yml that bumps your Poetry lock and Dockerfile base image weekly, grouped so PRs stay few, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads what is pinned where before it writes the config, because in a repository like cecilialee/boilerplate-fastapi-poetry-docker there are two version sources. pyproject.toml is a [tool.poetry] project with package-mode = false, python = "^3.11", fastapi = "^0.111.0" and pydantic-settings = "^2.3.1" as dependencies and ipykernel = "^6.29.4" in a dev group. poetry.lock was written by Poetry 1.8.3 (lock-version = "2.0") and resolves 68 packages, among them fastapi 0.111.0, pydantic 2.7.3, starlette 0.37.2 and uvicorn 0.30.1. Dockerfile starts FROM python:3.12.3-slim AS base, runs pip install poetry==1.8.3, copies pyproject.toml and poetry.lock, and installs with poetry install --without dev --no-root; docker-compose.yml only builds that Dockerfile and pins no image of its own. There is no .github directory, no tests and no workflow.

Then it measures how far behind the lock is, since that decides the grouping. poetry show --outdated in the sandbox lists most of the 68 packages: fastapi 0.111.0 against a current 0.162.4, ipykernel 6.29.4 against 7.4.0, httpx, anyio, click and the rest. The caret on ^0.111.0 means a new fastapi is outside the allowed range, so Dependabot will raise the constraint in pyproject.toml as well as the lock, and ipykernel 7 is a major bump. Docker Hub lists newer 3.12 patch tags than 3.12.3-slim, so the base image gets a pull request too. The agent also notes what a current Poetry says about the project: poetry check under Poetry 2 warns that [tool.poetry.description], readme and authors are deprecated in favour of [project] keys, and a poetry lock with Poetry 2 rewrites the file's header to lock-version = "2.1" even with nothing updated, which Poetry 1.8.3 in the Dockerfile still read in a dry-run install.

The config it writes, .github/dependabot.yml, has two entries. A pip entry at the root directory, which is the ecosystem Dependabot uses for Poetry projects, on a weekly schedule, with one group for minor and patch updates across all packages so a week's bumps arrive as one pull request, and major updates left to arrive on their own so ipykernel 7 is a separate decision; it labels the pull requests and sets an explicit open-pull-requests limit. A docker entry for the Dockerfile, weekly, so the python:3.12.3-slim base moves with new patch tags. No docker-compose entry, since the compose file names no image, and no github-actions entry, since there are no workflows yet.

Because there are no tests, the agent gives the reviewer something to run on each Dependabot pull request: it checks in the sandbox that poetry install --no-root from the lock works on Python 3.11, the floor ^3.11 names, and that fastapi dev app/main.py answers GET /api/v1/users/?token=morty with the two sample users and 422 without the token that app/dependencies.py requires, and writes those commands into the pull request as the manual check. On Python 3.13 the same install stops at the locked uvloop 0.19.0, which has no build for that interpreter, one concrete reason the weekly bumps are worth merging. It validates the YAML against the keys the Dependabot reference documents and names the Poetry version Dependabot runs, so the reviewer knows the lock header will change on the first update.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Dependabot to this Poetry project. Read pyproject.toml, poetry.lock (its header, lock-version and the pinned fastapi, pydantic, starlette and uvicorn versions), Dockerfile, docker-compose.yml, README.md and app/main.py first, then run poetry check and poetry show --outdated in your sandbox and record what they say. Write .github/dependabot.yml with a pip entry for the Poetry project on a weekly schedule, one group for minor and patch updates across all packages with majors left separate, labels and an explicit open-pull-requests-limit, and a docker entry for the Dockerfile's base image; add no entry for a file that pins nothing. Confirm that a current Poetry can read and relock this lockfile and say what changes in its header, and whether the Dockerfile's pinned Poetry 1.8.3 still reads the result. Since there are no tests, run poetry install --no-root and start the app once to find a request a reviewer can use to check each Dependabot pull request, and write it in the pull request. Open a pull request that pastes the outdated list and the checks.",
  "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

What comes back is a pull request that adds .github/dependabot.yml and changes nothing else: pyproject.toml, poetry.lock and Dockerfile are untouched, because Dependabot's own pull requests will move them. The description pastes poetry show --outdated from the sandbox, the poetry check warnings, the lock-version line before and after a relock with a current Poetry, and the dry-run install with Poetry 1.8.3 that read the relocked file.

It then says what to expect in the first week: one grouped pull request carrying every minor and patch bump in the lock, a separate pull request for ipykernel 7, a pull request raising fastapi past its caret, and a Docker pull request moving python:3.12.3-slim to the current 3.12 patch tag. For each, the manual check is the same two commands the agent ran, written out, since the repository has no test suite to lean on.

Before merging, a reviewer decides whether to move the deprecated [tool.poetry] fields to [project] first, so Dependabot's relocks land on a file a current Poetry is happy with, and whether the Dockerfile's poetry==1.8.3 should move to a Poetry 2 release in the same week, since the lock header will change on the first update either way.

Run it on every Monday morning

Dependabot itself runs on the schedule in the file. What a team adds on Rush is the review: an automation in the Project with a schedule trigger, cron 0 9 * * 1 with the trigger's timezone set to yours, runs a prompt that lists the open Dependabot pull requests, checks out each one, runs poetry install --no-root and the app's smoke request, and writes a short verdict on each pull request. A run that finds nothing open ends with a one-line note.

A team with several Poetry services sends one POST /o/{org}/sessions per repository from a script instead, 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. Each run opens at most one pull request.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A dependabot.yml is twenty lines, and the twenty lines are easy to get wrong in ways that only show a week later: the wrong ecosystem name for a Poetry project, a group that swallows a major bump, an entry for a compose file that pins nothing, a lockfile that a current Poetry rewrites in a format the Dockerfile's pinned Poetry has never seen. The agent reads the lock and the Dockerfile, runs Poetry in both versions in its own sandbox, and writes the config against what it saw, with the first week's pull requests described before they arrive.

Every command and its output stays on the run, so a reviewer reads the outdated list and the relock check without installing two Poetry versions. Several Poetry repositories can get the same config at once, each in its own sandbox, and a project whose lock a current Poetry cannot read is reported rather than given a config that will fail on its first run.

Frequently asked questions

Which package-ecosystem value is right for Poetry?

pip. Dependabot's supported-ecosystems table lists Poetry under the pip value, alongside pip, pip-compile and pipenv, and it detects the Poetry project from pyproject.toml and poetry.lock in the entry's directory. There is no separate poetry ecosystem name, and uv is a different value for a different lockfile.

Will Dependabot change pyproject.toml or only the lock?

Both when a new version is outside the constraint. fastapi = "^0.111.0" allows only 0.111.x, so moving to the current fastapi raises the caret in pyproject.toml and relocks; a patch bump inside a range changes only poetry.lock. The agent names which of the outdated packages fall in each case.

What happens to the lockfile header?

Dependabot relocks with a current Poetry, which writes lock-version = "2.1" and a new @generated by line where the committed file says 2.0 from Poetry 1.8.3. In the sandbox, Poetry 1.8.3 still performed a dry-run install from the relocked file, so the Dockerfile's pip install poetry==1.8.3 is not blocked by the first update; moving it to a Poetry 2 release is still recommended in the pull request.

Why is there no docker-compose entry?

Because docker-compose.yml only builds the local Dockerfile and names no image: tag, so a docker-compose entry would have nothing to update and would report an error on each run. The docker entry covers the base image in the Dockerfile, which is where the pinned python:3.12.3-slim lives.

How are grouped and major updates kept apart?

The pip entry's groups section has one group whose patterns match every package and whose update-types are minor and patch, so those arrive together weekly. A major bump, such as ipykernel 6 to 7, matches no group and opens its own pull request, which is the right size for a change that may need code edits.

More Poetry jobs

The same job on other stacks

Keep reading