Workflow Dependency Upgrade

workflow-dependency-upgrade

Structured runbook for the full upgrade lifecycle: triage → bump → test → triage breakage → PR hygiene.

Announce at start: "I'm using the workflow-dependency-upgrade skill to structure this dependency upgrade."

When to invoke

• Routine dependency sweep (scheduled or prompted by CI/tooling alerts).
• Triage and merge a batch of Dependabot or Renovate PRs safely.
• A CVE has been flagged in a dependency — need to patch and verify closure.
• Major-version migration with expected API breakage.

When NOT to invoke

• Design-time dep-graph minimization or supply-chain posture review → swe-workbench:principle-security.
• Release/version-bump mechanics (semver discipline, changelog, pre-release gate) → swe-workbench:principle-release-engineering.
• A full feature build that happens to bump a dep → /swe-workbench:implement.

Composition

• swe-workbench:principle-security — supply-chain integrity, CVE triage, SBOM, lockfile pinning, frozen installs.
• security-auditor agent — CVE confirmation and dependency-graph risk read.
• reviewer agent — breakage diff read for ambiguous API/type changes.

> Sub-skill: swe-workbench:workflow-commit-and-pr — used at Phase 5 for commit format enforcement and PR filing.

Phases

Phase 1 — Triage & batch

1. Classify each pending upgrade as patch, minor, or major.
2. Batch low-risk patch/minor upgrades together in one PR.
3. Pin/isolate majors and security-critical bumps — one per PR.
4. Prefer automated tools (Dependabot/Renovate) for routine patch/minor; manual sweeps for majors.

Phase 2 — Bump & regenerate lockfile

1. Use the ecosystem command matrix below to bump the manifest.
2. Regenerate the lockfile immediately after — never commit a stale lockfile.
3. Commit lockfile churn as a separate atomic commit from any code fixes.

Phase 3 — Build & test

1. Run full build + test + typecheck + lint.
2. Run the ecosystem audit command to confirm a patched CVE is actually closed.
3. If the audit still flags the CVE: a transitive pin may still reference the old version — inspect and force-resolve.

Phase 4 — Triage breakage

| Class | Typical cause | Action | |-------|--------------|--------| | Type / compile errors | API renamed or signature changed | Update call sites; consult reviewer for large diffs | | Behavioral test failures | Semantic change in dep behavior | Read changelog/release notes; update assertions | | Transitive / peer conflicts | Two deps require incompatible sub-dep | Force-resolve or isolate in its own PR | | CVE still flagged post-bump | Transitive pin to old version | Override transitive dep version explicitly |

Abort path: if a major upgrade won't reconcile cleanly, pin to last-good version and file an issue rather than ship a half-migration.

Phase 5 — PR hygiene & deliver

1. PR body must include: per-dep rationale, before/after versions, what broke and how fixed, audit/CVE evidence.
2. Keep lockfile changes and code fixes in separate reviewable commits.
3. Hand off to swe-workbench:workflow-commit-and-pr.

Ecosystem command matrix

| Ecosystem | Bump | Regen lockfile | Audit | |-----------|------|----------------|-------| | npm | npm update / npx npm-check-updates -u | npm install (auto) | npm audit | | pnpm | pnpm update | pnpm install (auto) | pnpm audit | | yarn | yarn upgrade | yarn install (auto) | yarn npm audit | | cargo | cargo update -p | cargo update (auto) | cargo audit | | pip/uv | uv add @latest | uv lock | pip-audit | | poetry | poetry add @latest | poetry lock --no-update | poetry audit (plugin) | | go | go get @latest | go mod tidy | govulncheck ./... | | bundler | bundle update | bundle install (auto) | bundler-audit check | | maven | mvn versions:use-latest-releases | auto | mvn dependency-check:check | | gradle | edit version in build file | ./gradlew dependencies | ./gradlew dependencyCheckAnalyze |

Common mistakes

| Mistake | Why it matters | |---------|----------------| | Batching a major with patches | Obscures API breakage risk; hard to revert one piece | | Editing manifest without regenerating lockfile | Produces a stale lockfile that diverges from what CI installs | | Skipping the audit re-check | CVE may persist through a transitive pin — bump alone is not enough | | Shipping a half-done major migration | Leaves the codebase in an inconsistent compatibility state | | Mixing lockfile + logic in one commit | Makes the diff unreadable and code review impractical |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lugassawan
• Source: lugassawan/swe-workbench
• License: MIT

Install and usage instructions live in the source repository linked above.