review-dependabot

Review Dependabot PRs

Workflow for FMC geo React apps. Dependabot config (groups, schedule, ignores, dependabot.yml changes) lives in skill tech-stack → references/dependabot.md. This skill covers review and merge decisions.

Repo scope

Work only in the Git repository of the current workspace — never review or merge Dependabot PRs for other repos. Run gh from the project root without --repo. Stop if the workspace is not a git repo or has no .github/dependabot.yml.

Typical FMC app repos target develop — never merge Dependabot PRs to main. Confirm baseRefName on each PR; use AskUserQuestion if it looks wrong.

Policy: one open Dependabot PR per ecosystem — merge or explicitly defer (close + ignore) before the next opens.

Review workflow

1. Gather context

gh pr list --author app/dependabot --state open --json number,title,baseRefName,headRefName,labels

For each open PR:

gh pr view <number> --json title,body,baseRefName,headRefName,mergeable,statusCheckRollup,author,labels
gh pr diff <number> --name-only

The PR body is the changelog. Use body from gh pr view for triage — do not fetch GitHub releases, npm pages, or other external changelogs unless the body is empty or clearly incomplete for a package you must decide on.

In grouped PRs, each package has its own section — scan all of them; one risky entry can block the whole group. Follow breaking change, migration, and deprecation headings in the body before reading the diff or grepping the codebase.

Note group name in the title (e.g. app-framework-minor-patch).

Also list the open security alerts — an empty PR list does not mean nothing is open:

gh api repos/{owner}/{repo}/dependabot/alerts \
  --jq '.[] | select(.state=="open") | "\(.dependency.package.name) \(.security_advisory.severity) \(.dependency.manifest_path) fixed in \(.security_vulnerability.first_patched_version.identifier)"'

2. Classify risk

Tier	Examples	Action
Low	Patch dev tools (knip, husky), typings, isolated utilities	CI green → merge
Medium	Grouped minor/patch framework deps, vite, oxlint/oxfmt, Playwright	Read PR-body release notes; spot-check usage; bun run build + bun oxlint locally if notes mention behavior changes
High	react, @tanstack/*, maplibre-gl, react-map-gl, prisma, better-auth, zod, tailwindcss, typescript majors	Read all PR-body notes + migration sections; grep codebase for affected APIs; run build, lint, unit tests; Playwright if maps/auth/routing touched; then merge when green
Critical decision	Semver major, explicit breaking changes, peer-dep conflicts, CI red, or changelog unclear	AskUserQuestion — do not merge until human chooses (the only tier that asks)

Security updates: treat as medium minimum — still read notes; do not merge blind even when labeled security. They bypass cooldown and may propose very fresh releases.

3. Investigate in code

When PR-body release notes or tier say investigate:

1. gh pr diff <number> — focus on package.json, not only lockfile noise.
2. Grep the local checkout for APIs mentioned in breaking sections (deprecated props, renamed exports, config keys).
3. Load the relevant FMC skill if the bump touches that area (react-dev, react-map-gl, tanstack-router-conventions, tanstack-start-conventions, playwright-skill, etc.).
4. Check peer-dependency warnings in CI logs.

browserslist bumps: Dependabot does not change the browserslist query — but lockfile may refresh caniuse-lite. After merge, ensure bun oxlint and bun run build still pass (skill tech-stack → references/browser-target.md).

GitHub Actions bumps: prefer grouped minor/patch; verify action release notes for runner/input renames; workflow must stay compatible with org secrets and permissions.

Docker bumps: monthly base images — check OS/package changes; rebuild locally if the app ships containers.

4. Security alerts without a PR (Bun)

In Bun repos Dependabot cannot open security-update PRs. GitHub files the alert under the npm ecosystem, so the security job runs as npm_and_yarn, ignores the package-ecosystem: bun entry and aborts on bun.lock. On the default branch this shows as a failed run named npm_and_yarn in /<dir> for <packages> - Update #…, repeated on every push while the alert is open.

This is not fixable in dependabot.yml or a workflow — do not try. We keep the failed run as the signal to bump by hand:

1. Take package, directory and fixed version from the alert list above.
2. Direct dependency: set the fixed version in package.json, then bun install in that directory. Transitive (bun why <package>): bump the parent, or use AskUserQuestion before adding an overrides entry.
3. Risk tier is medium minimum, as for any security update; read the advisory (gh api repos/{owner}/{repo}/dependabot/alerts/<number>) since there is no PR body.
4. Run the project check, commit via skill finish-work as Dev: Bump <package> to <version> with a body line saying it is a security fix, and push the way the repo normally takes changes.
5. Confirm the alert list is empty and the next push has no failed npm_and_yarn run.

5. When to use AskUserQuestion

Use AskUserQuestion when the agent cannot safely decide alone:

• Semver major for any production or framework dependency
• Breaking change affects code paths you cannot fully verify in session
• CI fails and fix is not obvious or would widen scope beyond the bump
• Grouped PR mixes safe and risky packages — merge all vs split vs close and reconfigure groups
• PR-body release notes missing or contradictory for a package you must decide on
• Proposed ignore rule vs taking the update now
• Merge vs wait for a sibling PR / upstream fix
• A known release has no version-update PR yet — may be in cooldown or waiting for the next scheduled check

Present concrete options, e.g. merge after local build, close and add ignore, or defer until next week.

6. Merge

Requirements:

• All required checks success (never merge red “to unblock the queue”)
• Risk tier handled per table above
• No unresolved review threads that block merge

Use rebase merge to keep history linear:

gh pr merge <number> --rebase --delete-branch

If the repo disallows rebase via CLI, use the GitHub UI with Rebase and merge.

Do not squash Dependabot PRs — preserve one commit per dependency bump for easier bisect.

After merge on develop, no further action unless CI on the base branch fails (then treat as a hotfix follow-up).

7. Defer instead of merging

Close without merging when:

• Major needs dedicated migration time
• Group is too large to review in one pass
• Known upstream regression (link issue in PR comment)

Prefer adding a targeted ignore in .github/dependabot.yml (document why in PR comment) over leaving the PR open — remember open-pull-requests-limit: 1 blocks the queue.

What not to do

• Do not refactor app code in the same session as a routine Dependabot merge unless the bump requires it
• Do not change CI workflows to make a bad bump pass — flag instead
• Do not report "all Dependabot work done" while a security alert is open, and do not try to silence the failed npm_and_yarn security run
• Do not batch-merge multiple open Dependabot PRs without reviewing each