Dependency Update Review Rules

Purpose

Use these rules when an AI coding assistant, dependency bot, or human maintainer proposes package updates. The goal is to keep routine patch updates fast while forcing risky dependency changes through a source-backed review.

Dependency updates are code changes. A one-line manifest bump can alter runtime behavior, build output, install-time scripts, native extensions, transitive dependency trees, licenses, and vulnerability exposure.

Update Classification

Classify the update before reviewing style or merge convenience.

1. Security fix. An advisory, CVE, Dependabot security alert, or OSV match says the installed version is vulnerable.
2. Patch or minor update. SemVer suggests backward compatibility, but changelogs and lockfiles still need review.
3. Major update. The package declares breaking-change risk or shifts public APIs, runtime support, configuration, or generated output.
4. Build or release tooling. Bundlers, compilers, test runners, linters, package managers, CI actions, Docker bases, and publishing tools can affect every artifact even when application code is unchanged.
5. New dependency or registry source. A newly introduced package, git URL, tarball URL, private registry, alternate registry, or postinstall script needs provenance review before merge.
6. Transitive churn. A small direct update may replace many nested packages; review the lockfile and security impact before accepting it.

When the class is unclear, treat the update as high risk until release notes, dependency-review output, or package-manager evidence explains the change.

Required Evidence

A dependency update PR should include enough evidence for a reviewer to understand what changed and why.

• Manifest and lockfile changes are present together when the package manager expects a lockfile.
• Release notes, changelog entries, advisory records, or migration notes cover every direct dependency update.
• Dependency review, advisory scanning, or an equivalent local report is clean or has documented exceptions.
• CI ran on the reviewed head commit with tests that exercise affected runtime, build, and integration paths.
• New packages have source, license, maintainer, install-script, and registry provenance reviewed.
• Major upgrades name the breaking-change surface and the migration evidence.
• Security updates name the vulnerable package, affected range, fixed range, and why the selected version is sufficient.
• Rollback, pinning, or emergency revert steps are clear for production-facing updates.

Do not accept "the bot opened it" or "tests passed locally" as enough evidence for a dependency update that changes runtime, build, deploy, or security behavior.

Review Rules

• Review the lockfile first; it reveals transitive churn that the manifest may hide.
• Split security fixes from broad modernization work unless the fix cannot be applied without the larger upgrade.
• Split unrelated major version updates into separate PRs so failures can be bisected and reverted.
• Prefer the smallest fixed version that resolves a security advisory when a broader upgrade would increase compatibility risk.
• Confirm that package-manager commands were run from the expected workspace, with the expected package-manager version and registry configuration.
• Require tests around affected imports, generated clients, browser bundles, migrations, CLIs, server startup, or plugin loading paths.
• Re-check dependency-review output after a rebase or force push because the base branch can change the lockfile and advisory diff.
• Treat install scripts, native binaries, code generation, and release tooling as privileged execution paths.

Merge Blockers

Block merge until resolved when:

• the manifest changed without the expected lockfile update;
• the lockfile changed without a matching source change or explanation;
• a dependency points to a new registry, tarball, git URL, fork, or unpinned source without provenance review;
• dependency review, advisory scanning, or CI reports a new high-severity issue that is not triaged;
• a major upgrade lacks migration notes, compatibility tests, or owner review;
• security-advisory details are copied into public comments with private package names or exploit context;
• generated artifacts changed but the generator version, command, or source input is missing;
• the update changes package-manager behavior, publish automation, CI actions, or build tooling without release-owner review.

Review Checklist

• {"task": "Update class named", "description": "The PR explains whether this is a security, patch, minor, major, build-tool, new-dependency, or transitive update"}
• {"task": "Source evidence linked", "description": "Release notes, changelog entries, advisory records, or migration notes cover the direct updates"}
• {"task": "Lockfile reviewed", "description": "Manifest and lockfile changes match the package-manager expectations, and transitive churn is understood"}
• {"task": "Scanners triaged", "description": "Dependency review, advisory checks, or equivalent local reports are clean or have documented exceptions"}
• {"task": "Compatibility tested", "description": "CI and targeted tests cover the runtime, build, integration, or generated-code paths touched by the update"}
• {"task": "Privacy protected", "description": "Private package names, registries, advisory details, and full lockfile contents are not exposed publicly"}

AI Review Rules

AI assistants can help summarize dependency diffs, but reviewers should require source evidence and current check results.

• Ask the assistant to classify the update before asking for an approval recommendation.
• Require the assistant to list every changed direct dependency and summarize transitive churn separately.
• Have the assistant quote package names and versions from the manifest or lockfile rather than relying on PR titles.
• Keep private dependency metadata out of public lookups unless explicitly approved.
• Re-run the review after rebases, force pushes, or package-manager lockfile regeneration.

Troubleshooting

• Patch update breaks tests: inspect transitive dependency changes and generated artifacts before assuming the direct package broke compatibility.
• Security update requires a major version: isolate the security fix, name the breaking changes, and require owner review for the migration.
• Dependency review shows a new advisory: confirm whether the selected version is affected, whether a fixed range exists, and whether a temporary pin or replacement is safer.
• Lockfile is noisy: regenerate with the repository's documented package manager and version; avoid mixing npm, pnpm, Yarn, Poetry, Cargo, or Go module behavior in one PR.
• Private packages are involved: keep package names, versions, advisory details, and registry URLs in private review channels.

Duplicate And History Check

Checked existing rules, guides, hooks, commands, skills, open PRs, and closed PR history for dependency update rules, supply-chain dependency review, Dependabot review, lockfile review, OSV advisory review, dependency-security hooks, and Scorecard-based dependency risk review.

Adjacent content includes the /dependency-risk-review command, dependency update checker hook, dependency security scanner hook, lockfile provenance checker hook, review-AI-generated-code guide, and high-risk code review escalation rules. This entry is distinct because it is a portable rules policy for deciding when dependency update PRs have enough source evidence, lockfile integrity, compatibility testing, and privacy-safe advisory handling to merge.

Where Dependency Review Runs

GitHub's dependency review surfaces in two places. Use the table below to decide which one a PR's evidence should reference.

Either way, dependency review informs you of:

• Which dependencies were added, removed, or updated, along with the release dates
• How many projects use these components
• Vulnerability data for these dependencies

Sources

• GitHub Docs: About dependency review - https://docs.github.com/en/code-security/concepts/supply-chain-security/about-dependency-review
• GitHub Docs: Configure Dependabot version updates - https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-version-updates
• GitHub Docs: About Dependabot security updates - https://docs.github.com/en/code-security/concepts/supply-chain-security/about-dependabot-security-updates
• Semantic Versioning - https://semver.org/
• OSV documentation - https://google.github.io/osv.dev/

• Source repositorygithub.com 2026-07-19T11:20:19-07:00
• Documentationdocs.github.com
• Submitted by MkDev112026-06-04