| name | dependency-management |
| description | Guides dependency version management, Dependabot configuration, and upgrade workflows. Use when adding, updating, or auditing dependencies in the workspace. |
Dependency Management
When to use
- Adding or updating dependencies in any workspace package
- Configuring or modifying Renovate or Dependabot
- Reviewing Dependabot PRs
- Reviewing Renovate PRs
- Auditing dependencies for security or currency
- Troubleshooting dependency resolution or lockfile issues
Target model
renovate.json is the primary dependency update policy..github/dependabot.yml is retained only for GitHub-native security update surfaces.- Routine version updates do not belong in Dependabot anymore.
This split exists because the repo needs:
- bounded routine PR volume
- visible majors without queue sprawl
- security updates that are easy to identify and prioritize
- automatic routine coverage for future workspace packages
- less Release Please churn from scattered dependency merges
Renovate configuration
The Renovate config lives at renovate.json.
How it works
- Checks on a weekly cadence to keep routine merges batched
- Uses
config:best-practices as the base preset
- Batches all npm minor and patch updates into a single non-major group
- Keeps GitHub Actions non-majors in their own group
- Auto-merges bounded non-major updates after CI passes
- Holds majors behind Dependency Dashboard approval
- Applies a 3-day
minimumReleaseAge cooldown before automerge, with internalChecksFilter: strict, as a supply-chain guard
- Keeps concurrent routine PR volume capped
- Uses semantic commit messages so Release Please can trace dependency work cleanly
Current grouping posture
- All npm non-majors (minor and patch) batch into one
npm non-major group
- GitHub Actions non-majors are grouped together, separate from npm
- Lock file maintenance runs as its own low-risk stream
- Major updates are never grouped into routine flow; they stay dashboard-gated
- Security fixes are exempt from the release-age cooldown so remediation stays immediate
Major updates
- Major updates are never auto-merged
- Major updates require explicit Dependency Dashboard approval
- Review them on purpose, not in the background queue
Dependabot configuration
The Dependabot config lives at .github/dependabot.yml.
It is now security-only:
- npm security updates only
- GitHub Actions security updates only
open-pull-requests-limit: 0 disables routine version-update PRs while preserving security-update behavior- Security PRs are labeled for visibility and reviewed manually
Reviewing dependency PRs
Routine Renovate PRs
- Check the changelog or release notes linked in the PR
- Confirm the PR matches the expected grouping boundary
- Let CI finish before taking action
- If the update is non-major and CI is green, the repo policy may auto-merge it
- If the PR reveals a behavioral break, disable or narrow the matching rule rather than silently tolerating queue drift
Security PRs
- Review security PRs first
- The repo may auto-merge vulnerability PRs after checks pass when the Renovate config allows it
- Confirm the PR is a straightforward vulnerability fix and not a disguised migration
- If a fix fails checks or needs code changes, treat it as a manual exception instead of widening the rule casually
- Keep major upgrades and config migrations out of the “merge it automatically” mental model
Backlog recovery
When the dependency queue becomes noisy again, recover in this order:
- Bucket all open work into security, non-major, and major
- Fix security work first
- Close or replace stale routine PRs after the repo policy is correct
- Let grouped non-major flow resume
- Hold majors in the dashboard instead of leaving them in the open PR queue
- Only widen automerge after the queue is stable
Adding dependencies
When adding a new dependency:
- Use
pnpm add <package> (or pnpm add -D <package> for dev dependencies)
- Always add to the specific workspace package, not the root:
pnpm --filter <package> add <dep>
- Use caret ranges (
^) for semver-compatible updates (default)
- After adding, verify:
pnpm install, pnpm test, pnpm run build
- Check whether the new package belongs in an existing Renovate grouping rule. If you add a new workspace package or a noisy dependency family, update
renovate.json so the queue shape stays intentional.
Upgrading dependencies manually
For immediate upgrades (not waiting for Dependabot):
pnpm outdated -r
pnpm --filter <workspace> update <package>
pnpm --filter <workspace> update
pnpm --filter <workspace> update --latest
After upgrading, always run tests and build before committing.
Security
- Dependabot alerts are enabled for vulnerability notifications
- Dependabot security updates remain enabled as the GitHub-native security surface
- Renovate is not the routine security bottleneck. Security work skips normal queue expectations and is handled first
- If a security alert requires immediate action, don't wait for the weekly cycle — upgrade manually
Transitive security overrides
When a transitive dependency carries a vulnerability and its direct parents cap it below the fixed version, use a pnpm override in pnpm-workspace.yaml (overrides:) to force the patched version. Verify the build and tests pass under the override before relying on it, because forcing a transitive bump can break a parent that expected the older API.
Current overrides:
| Package | Pinned to | Reason | Remove when |
|---|
esbuild | 0.28.1 | GHSA-g7r4-m6w7-qqqr (dev-server file read). astro and vite cap esbuild below 0.28.1. | astro/vite widen their esbuild range to include the fix, then pnpm update resolves it natively. |
CI security scanning
Four repo security scanning workflows run on pushes to main and on PRs:
| Workflow | File | What it checks |
|---|
| Secret Scan | secret-scan.yml | gitleaks CLI scans for accidentally committed secrets |
| Supply Chain | supply-chain.yml | Shai-Hulud 2.0 Detector scans for compromised npm packages |
| CodeQL | codeql.yml | Static analysis for security vulnerabilities in JS/TS |
| Scorecard | scorecard.yml | OSSF supply chain security posture scoring |
gitleaks uses the MIT-licensed CLI directly (not the commercial gitleaks-action) to avoid org license requirements. The CLI version is pinned in the workflow and must be updated manually. CodeQL and Scorecard also run on a weekly schedule. A fifth live scan (security-scan-live.yml) runs after deployments and on manual dispatch.
Updating pinned tool versions
Some tools are pinned outside of Dependabot's reach:
| Tool | Where pinned | How to update |
|---|
| gitleaks CLI | GITLEAKS_VERSION env var in secret-scan.yml | Check gitleaks releases, update the version string |
| GitHub Actions | Workflow uses: references | Renovate handles routine update PRs according to renovate.json |
Enablement
This repo config assumes the Renovate GitHub App is installed for the repository. Setup steps live in docs/infra/renovate-app-setup.md.
For Renovate-specific config changes, live-doc grounding, config migration PRs, and safe automerge tuning, use .cursor/skills/renovate-operations/SKILL.md.
Version policy
- Node.js: track active LTS. Keep the repo’s minimum supported version in
package.json engines.node and revisit periodically. Do not adopt current/development releases.
- pnpm: track latest stable 11.x. Evaluate 12.x when it stabilizes.
- Astro/Starlight: track latest stable 5.x. Evaluate Astro 6.x when it exits beta.
- Vitest: track latest stable 4.x.
- TypeScript: track latest stable 5.x. Evaluate 6.x when it exits beta.
When a major version upgrade is available, create a dedicated branch and PR for it. Do not bundle major upgrades with other changes.
© 2026 Mikey Sebastian Drozd. Licensed under CC BY 4.0. Repository code and tooling: MIT.
Source: https://github.com/Mikeys-Tech-Lab/poc/blob/main/.cursor/skills/dependency-management/SKILL.md
