Fixes and pull requests
Every finding names its fix. For the levels you choose, watchdep can also open a pull request with the upgrade, from your own CI, with your repository’s own token. A person reviews and merges it: watchdep never merges. A finding is fixed only when production has the fixed version, not when the pull request merges.
Fix settings
Per application, for each level, owners and admins choose (the application’s “Fixes” button):
| Setting | What happens |
|---|---|
| Name the fix | The finding shows the fix. This is the default at every level. |
| Open a pull request | watchdep fix, run in the project’s CI, opens a pull request for each finding at that level that has a fix version. |
Each part can override any level; a part left at “As the application” follows the application’s setting. So Prospec360 could open pull requests for severe and high findings everywhere, except in one part where it only names them.
Naming the fix
Naming the fix is what every finding shows anyway: the lowest fixed version on the major line in use, or, when there is none, the lowest fixed version overall, marked as a new major version in deep orange. For example “Upgrade rack to 2.2.3.1, same major line”, or “No fixed version published”. Links to the advisories are alongside.
How pull requests are opened
The server only says what to upgrade. It never holds write access to a repository and never runs a package manager. Pull requests are opened by watchdep fix, in the project’s own CI through watchdep-action, with that repository’s own token. See CI.
watchdep fix asks the server for the part’s open, confirmed vulnerability findings whose level is set to “open a pull request” and that have a fix version. For each one it:
- makes a branch
watchdep/<advisory id>-<part>; - runs the fixer for the file’s package manager;
- takes the inventory again, which must show the package at or above the fix version. If it does not, or the package is no longer found in its file, the files are put back exactly as they were and the fix is named, with the reason;
- commits and pushes;
- opens one pull request per finding per part, or updates the one already open.
Each run also reads the state of the pull requests it opened before and reports what changed. --dry-run makes the changes, prints them and puts the files back (a moved Dockerfile digest included), with no git and no pull request.
What the server sends is checked before anything changes. The server only names what to upgrade, and watchdep fix does not trust it further than that. It refuses, and names the fix instead, when the file to change is outside the repository (after following symbolic links), when the package name does not fit the package manager’s rules or starts with - (so it can never read as a flag), or when the version is not a plain version (no range, address, github: or file spec).
In GitHub Actions the job needs permissions: contents: write, pull-requests: write, and the project’s package manager set up before the watchdep step, as your own CI already does:
permissions:
contents: write
pull-requests: write
jobs:
fix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0 # a release listed in the Action's checksums/
command: fix
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
The fixers
A dependency the part declares itself (direct) is upgraded to exactly the fix version, never a range that could pull in a newer release nobody reviewed. One that comes in through another package is fixed with the package manager’s own override, or with its targeted update. The pull request says which.
| Package manager | A direct dependency | A dependency that comes in through another |
|---|---|---|
| npm | npm install --save-exact --ignore-scripts <package>@<fix> |
override: overrides in package.json, then npm install --ignore-scripts |
| yarn classic | yarn add --exact --ignore-scripts <package>@<fix> |
override: resolutions in package.json, then yarn install --ignore-scripts |
| yarn berry | yarn up --exact <package>@<fix>, scripts off |
override: resolutions in package.json, then yarn install --mode=skip-build |
| pnpm | pnpm add --save-exact --ignore-scripts <package>@<fix> |
override: pnpm.overrides in package.json, then pnpm install --ignore-scripts |
| bun | bun add --exact --ignore-scripts <package>@<fix> |
override: overrides in package.json, then bun install --ignore-scripts |
| Composer | composer require --no-scripts --no-plugins <package>:<fix> |
targeted update: composer update --with-dependencies --no-scripts --no-plugins <package> |
| Bundler | targeted update: bundle update --conservative <package> |
the same |
| pip requirement files | the requirement is pinned to ==<fix> |
the same |
| poetry | poetry add <package>==<fix> |
targeted update: poetry update <package> |
| uv | targeted update: uv lock --upgrade-package <package>==<fix> |
the same |
| pipenv | pipenv install <package>==<fix> |
targeted update: pipenv update <package> |
| Go modules | go get <module>@v<fix>, then go mod tidy |
the same |
| Cargo | cargo update -p <crate> --precise <fix> |
the same |
| Dockerfile base images pinned by digest | the digest moves to the tag’s current digest, which carries the distribution’s fixed packages |
An override pins the package until the dependency that brings it in ships the fix; the pull request says to remove the override then. Maven, Gradle and NuGet have no fixer yet: their fixes are named. A package manager that is not installed on the runner is reported, and the fix named.
What the package manager can see
A package manager may run code from the packages it fetches, so watchdep gives it as little as it can:
- Install scripts are off for npm, yarn, pnpm and bun, and Composer runs with scripts and plugins off.
- A minimal environment. Every package manager gets
PATH,HOME, the locale, temporary folders, proxies, certificate settings and its own settings (npm_config_,BUNDLE_,PIP_,CARGO_,GOand the like), and never a variable whose name looks like a credential (one holdingTOKEN,SECRET,PASSWORD,CREDENTIALorAUTH, or ending_KEY, in any case). SoGITHUB_TOKEN,WATCHDEP_TOKENandNODE_AUTH_TOKENnever reach it. A private registry needs its credentials in the package manager’s own configuration file (.npmrc,auth.json, Bundler’s config); otherwise the install fails and the fix is named.
Base images
After a Dockerfile’s digest moves, watchdep reads the new image, as --image would, to check it carries the fixed operating system package. If it still carries a version below the fix, the Dockerfile is put back and the fix named: the distribution has not shipped it to that image yet. If the new image cannot be read, the change stays, and the pull request says plainly: “Not verified: watchdep could not show this fix in a fresh inventory”, with the reason, and asks you to check the rebuilt image before merging.
The pull request
The description names the advisory and its level; why it matters (the ranking reason and labels such as exploited now); what changes in each place, with the strategy; up to three dependency paths; a new major version, when it is one; the code check’s draft verdict and evidence; the advisories; and a link to the finding. It ends:
Your CI tests this change. A person approves and merges it: watchdep never merges.
A person merges every pull request. watchdep has no merge, approve or auto-merge call at all. An agent connected to watchdep cannot open pull requests either.
What production means
A finding is fixed when production has no affected place left. What production is depends on the part:
- Without deployment reports, production is the head of the part’s production branch. A fix merged into the production branch leaves the finding at “fix pull request open”, logged “merged into main: fixed when the next inventory of main shows it”; the next inventory decides. Merged into another branch, the finding is “fix merged, not yet in production”.
- With deployment reports, production is the last deployed commit, and its inventory is the part’s production inventory. A merged fix is “fix merged, not yet in production” until the deployed commit’s inventory shows the fixed version, and then it is fixed. Inventories of the production branch that were not deployed raise no findings (a malicious release in one is still alerted at once).
Report a deployment from the deploy step, and take an inventory in the same step so the deployed commit has one:
watchdep scan
watchdep deployed --sha "$GITHUB_SHA"
A deployed commit with no inventory is shown on the part in deep orange: “run watchdep scan in the deploy step”. The part’s page says which rule it is on, for example “production is the last deployed commit a41f9c2” or “the head of main”.
A pull request closed without merging returns the finding to the state it had before (new or acknowledged). Every change is logged by the CLI with its token: opened (waiting for a person to merge), merged, closed. The finding page’s Fix block shows the pull request, its part and strategy, and “Waiting for a person to merge”, “Merged into main 12 November 2026” or “Closed without merging”. See Decisions and a finding’s life.