feat: Add reusable workflow for dependency bump review

dvasilas · dvasilas · commit b431eccb753f · 2026-03-19T11:37:23.000+02:00
Adds claude-code-dependency-review.yml, a reusable workflow that runs
the /review-dependency-bump skill to evaluate dependabot PRs.
diff --git a/.claude/skills/review-dependency-bump/SKILL.md b/.claude/skills/review-dependency-bump/SKILL.md
@@ -0,0 +1,297 @@
+---
+name: review-dependency-bump
+description: Use when dependabot PRs need safety assessment before merging, when asked to review automated dependency updates, or when determining merge risk for version bumps
+argument-hint: [pr-number-or-url]
+---
+
+# Evaluating Dependency Bump PRs
+
+## Overview
+
+Systematic approach to evaluating dependency bump PRs for breaking changes and merge safety. Examines semantic versioning implications, release notes, commit messages, and codebase impact before providing merge recommendations.
+
+Works in two modes:
+- **Single PR mode**: evaluate one specific dependency bump PR (from dependabot or human-authored)
+- **All dependabot PRs mode**: list and evaluate all open dependabot PRs in the repo
+
+**Integration with code review:** This methodology applies to any PR that modifies dependency files (`go.mod`, `package.json`, `Cargo.toml`, etc.), not just dependabot PRs. When reviewing a PR via `/review-pr` that includes dependency changes, invoke `/review-dependency-bump` to perform this analysis.
+
+## Determine Mode
+
+Parse `$ARGUMENTS` to decide the mode:
+
+### Single PR mode
+
+Activated when `$ARGUMENTS` is provided.
+
+- If arguments contain `REPO:` and `PR_NUMBER:` (CI mode), extract those values. Set output to **GitHub comment mode**.
+- If the argument is a GitHub URL (starts with `https://github.com/`), extract `owner/repo` and the PR number from it. Set output to **local mode**.
+- If the argument is just a number, use the current repo from `gh repo view --json nameWithOwner -q .nameWithOwner`. Set output to **local mode**.
+
+Then skip to **Gather PR Details** (step 2).
+
+### All dependabot PRs mode
+
+Activated when `$ARGUMENTS` is empty. Output is always **local mode**.
+
+Start from **List All Dependabot PRs** (step 1).
+
+## Methodology
+
+### 1. List All Dependabot PRs (all PRs mode only)
+
+```bash
+gh pr list --author "app/dependabot" --state open --json number,title,headRefName,url
+```
+
+Create TodoWrite list tracking analysis of each PR.
+
+### 2. Gather PR Details
+
+For each PR, fetch details in parallel:
+
+```bash
+gh pr view <number> --repo <owner/repo> --json body,title,files,statusCheckRollup
+```
+
+Extract from PR body:
+- Version change (old -> new)
+- Links to commits/release notes
+- Compatibility scores if present
+
+Check CI status from `statusCheckRollup`. If any required checks failed, the recommendation must not be SAFE TO MERGE regardless of other analysis.
+
+### 3. Analyze Semantic Versioning (Heuristic Only)
+
+Identify the bump type (patch, minor, major). Use this as an initial signal to prioritize review depth — not as a substitute for thorough analysis. Many projects don't follow semver strictly, and even patch bumps can introduce behavioral changes.
+
+Always perform steps 4–8 regardless of bump type.
+
+**Signals that warrant extra scrutiny:**
+- Major version bumps (X.0.0) - breaking changes likely
+- Pre-1.0 versions (0.x.y) - minor bumps may break
+- Multiple version jumps (1.2.0 -> 1.5.0) - review all intermediate releases
+- Projects with no stated semver policy
+
+### 4. Examine Release Notes
+
+From the PR body fetched in step 2, extract links to release notes or changelogs.
+
+If the PR body links to a GitHub releases page, use the WebFetch tool to fetch it and extract release notes, breaking changes, and upgrade notes.
+
+**What to look for:**
+- "BREAKING CHANGE" or "Breaking:" sections
+- "Migration guide" or "Upgrade notes"
+- Deprecation warnings
+- Security fixes
+- Bug fixes that change behavior
+
+### 5. Examine Commit Messages (Fallback)
+
+If release notes unavailable, check commits from PR body links:
+
+**Look for patterns:**
+- `fix:` - bug fixes (usually safe)
+- `feat:` - new features (check if additive)
+- `BREAKING CHANGE:` - explicit breaking changes
+- `refactor:`, `perf:` - behavioral changes possible
+- Commit titles mentioning "breaking", "incompatible", "remove"
+
+### 6. Check Codebase Impact
+
+Search the codebase for patterns that might be affected using the Grep tool:
+
+- Search for function names, types, or constants mentioned in breaking changes or deprecation notices
+- Search for import paths of the updated dependency
+- Example: if release notes mention a credential signing change, search for `Transfer-Encoding`, `S3 Accelerate`, etc.
+- Example: if an API was deprecated or removed, search for `<affected-function-name>`, `<deprecated-api>`
+
+When the dependency source code is available locally, inspect it directly for a more reliable assessment:
+
+- **Go with vendoring:** The vendor directory is part of the PR diff. Read the changed files under `vendor/` to see exactly what changed in the dependency code.
+- **Node.js:** If `node_modules` is already present, inspect the dependency source directly to see what changed.
+- **Other ecosystems:** Check if the dependency source is committed or cached locally.
+
+This is more reliable than release notes alone — it shows the actual code changes affecting the project.
+
+**Key question:** Does this codebase use the features that changed?
+
+### 7. Assess Security Implications
+
+Evaluate the security impact of the dependency bump:
+
+- **Known vulnerabilities:** Check if the bump fixes CVEs or security advisories. Look for "Security" or "CVE" mentions in release notes and commit messages.
+- **New dependencies:** Check if the bump introduces new transitive dependencies that expand the attack surface.
+- **Sensitive code paths:** Pay special attention to changes in authentication, authorization, cryptography, network communication, input parsing, and serialization logic.
+- **Supply chain signals:** Look for maintainer changes, suspicious commits, or unusual release patterns (e.g., a long-dormant package suddenly publishing updates).
+
+If the dependency handles credentials, tokens, TLS, or request signing, flag this for human review regardless of semver bump type.
+
+**Source code security scan:** When the dependency source code is available locally (Go vendor directory, or pre-populated `node_modules`), dispatch an Explore sub-agent to scan **changed files in the dependency source code** for suspicious patterns:
+
+- Obfuscated or minified code where none existed before
+- `eval()`, `exec()`, `child_process`, `os/exec`, `net/http` calls introduced in unexpected places
+- Hardcoded IP addresses, URLs, or encoded strings
+- File system access, network calls, or environment variable reads that don't match the library's purpose
+- Install hooks (`postinstall`, `preinstall`) that download or execute external resources
+
+Scope the scan strictly to changed dependency files to avoid unbounded analysis. Report any findings with file paths and line numbers.
+
+### 8. Verify PR Authorship
+
+Before deciding whether to approve, check that every commit in the PR is authored by dependabot:
+
+```bash
+gh pr view <number> --repo <owner/repo> --json commits --jq '.commits[].authors[].login'
+```
+
+If any commit author is not `dependabot[bot]`, **NEVER approve the PR** — post a comment instead, regardless of the recommendation. **Only pure dependabot PRs may be approved**.
+
+### 9. Provide Structured Recommendations
+
+Format depends on output mode determined earlier.
+
+#### Local mode
+
+For each PR, output:
+
+```markdown
+### PR #X: <title>
+**Version change:** <old> -> <new>
+
+**Changes:**
+- Key change 1
+- Key change 2
+
+**Breaking changes:** None | <description>
+
+**Security concerns:** None | <description>
+
+**Impact on codebase:** <verified usage patterns>
+
+**Recommendation:** SAFE TO MERGE | REVIEW REQUIRED | BREAKING CHANGES
+
+**Notes:** <specific risks or considerations>
+```
+
+#### GitHub comment mode (CI)
+
+**The command must stay on a single bash line.** Use `$'...'` quoting with `\n` for line breaks. Escape single quotes as `\'`.
+
+**Duplicate prevention:** Before posting, check for an existing evaluation comment by searching for the `— Claude Code` marker:
+
+```bash
+gh pr view <number> --repo <owner/repo> --json comments --jq '.comments[] | select(.body | contains("— Claude Code")) | .url'
+```
+
+If a previous evaluation exists, edit it instead of creating a new comment. If the recommendation changed from a previous comment to SAFE TO MERGE, delete the old comment and approve instead.
+
+Choose one of the following based on the recommendation:
+
+##### SAFE TO MERGE: approve the PR with the evaluation as the review body
+
+Only if the authorship check (step 8) confirmed all commits are by dependabot. Otherwise, post a comment instead.
+
+Do NOT post a separate comment. The approval review body carries the evaluation.
+
+```bash
+gh pr review <number> --repo <owner/repo> --approve --body $'## Dependency Bump Evaluation\n\n**Version change:** <old> -> <new> (patch|minor)\n**Breaking changes:** None\n**Security concerns:** None\n**Impact on codebase:** No affected patterns found\n**Recommendation:** SAFE TO MERGE\n\n— Claude Code'
+```
+
+##### REVIEW REQUIRED or BREAKING CHANGES: post a comment (do NOT approve)
+
+```bash
+gh pr comment <number> --repo <owner/repo> --body $'## Dependency Bump Evaluation\n\n**Version change:** <old> -> <new>\n**Semver bump type:** patch | minor | major\n\n**Changes:**\n- Key change 1\n- Key change 2\n\n**Breaking changes:** None | <description>\n\n**Security concerns:** None | <description>\n\n**Impact on codebase:** <verified usage patterns>\n\n**Recommendation:** REVIEW REQUIRED | BREAKING CHANGES\n\n**Notes:** <specific risks or considerations>\n\n— Claude Code'
+```
+
+### 10. Suggest Merge Order (all PRs mode only)
+
+For multiple PRs with dependencies:
+
+1. Lowest-level dependencies first (config, utils, core libs)
+2. Mid-level dependencies (auth, API clients)
+3. Highest-level dependencies (service-specific SDKs)
+
+**Example:**
+```
+1. PR #64 (config) - lowest level
+2. PR #65 (credentials) - depends on config
+3. PR #66 (S3 service) - depends on both
+```
+
+## Monorepo / Scoped Package Dependencies
+
+When multiple dependabot PRs update packages from the same ecosystem (e.g., `@aws-sdk/*`, `@babel/*`, `@types/*`):
+
+1. **Identify related PRs** - group PRs by package scope/org
+2. **Check for shared changelog** - monorepo packages often share a single changelog or release notes page
+3. **Evaluate together** - breaking changes in a core package may affect all scoped packages
+4. **Merge as a batch** - related scoped packages should typically be merged together to avoid version mismatches
+
+## Risk Assessment Matrix
+
+| Scenario | Risk | Action |
+|----------|------|--------|
+| Patch bump + bug fixes only | Low | Review release notes, merge after CI passes |
+| Minor bump + additive features | Low-Medium | Review release notes, verify no deprecated API usage |
+| Major bump | High | Review breaking changes, update code |
+| Security fix in any version | Critical | Merge promptly after verification |
+| Multiple version jumps | Medium | Review all intermediate releases |
+| Codebase uses affected features | High | Test thoroughly, may need changes |
+| Codebase doesn't use affected features | Low | Safe to merge |
+| CI checks failing | High | Do not merge until CI is green |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Trusting semver at face value | Semver is a heuristic; always examine release notes or commits |
+| Assuming patches are always safe | Patches can change behavior when fixing bugs |
+| Not verifying codebase impact | Search for affected functions/patterns |
+| Recommending "just test it" without analysis | Provide informed assessment first |
+| Ignoring security fixes | Prioritize security updates |
+| Missing dependency order | Consider merge order for related deps |
+| Skipping commit messages | When release notes unavailable, commits are critical |
+| Not reading breaking change sections | Look for "BREAKING", "Migration", "Upgrade" keywords |
+
+## Example Workflows
+
+### Single PR (local)
+
+```
+User: "/review-dependency-bump 42"
+
+1. Fetch PR #42 details
+2. Identify version bump type
+3. Fetch release notes or commits
+4. Search codebase for affected patterns
+5. Output structured recommendation as text
+```
+
+### Single PR (CI)
+
+```
+Arguments: "REPO: owner/repo PR_NUMBER: 42"
+
+1. Fetch PR #42 details from owner/repo
+2. Identify version bump type
+3. Fetch release notes or commits
+4. Search codebase for affected patterns
+5. Post structured recommendation as GitHub comment
+```
+
+### All dependabot PRs
+
+```
+User: "/review-dependency-bump"
+
+1. Use TodoWrite to create analysis checklist
+2. List all open dependabot PRs
+3. For each PR (in parallel):
+   - Fetch PR details
+   - Identify version bump type
+   - Fetch release notes or commits
+   - Search codebase for affected patterns
+4. Provide structured recommendations with risk levels
+5. Suggest merge order if applicable
+```
diff --git a/.github/workflows/claude-code-dependency-review.yml b/.github/workflows/claude-code-dependency-review.yml
@@ -0,0 +1,52 @@
+name: Claude Code Dependency Review
+
+on:
+  workflow_call:
+    secrets:
+      GCP_WORKLOAD_IDENTITY_PROVIDER:
+        required: true
+        description: GCP Workload Identity Provider for Vertex AI
+      GCP_SERVICE_ACCOUNT:
+        required: true
+        description: GCP Service Account for Vertex AI
+      ANTHROPIC_VERTEX_PROJECT_ID:
+        required: true
+        description: GCP project ID for Vertex AI
+      CLOUD_ML_REGION:
+        required: true
+        description: GCP region for Vertex AI
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+
+      - name: Run Claude Code Dependency Review
+        id: dependency-review
+        continue-on-error: true
+        uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ github.token }}
+          use_vertex: "true"
+          prompt: "/review-dependency-bump REPO: ${{ github.repository }} PR_NUMBER: ${{ github.event.pull_request.number }}"
+          claude_args: |
+            --allowedTools "Read" "Grep" "WebFetch" "Bash(gh repo view *)" "Bash(gh pr view *)" "Bash(gh pr comment *)" "Bash(gh pr review *)" "Bash(gh api *)"
+            --model "claude-opus-4-6"
+        env:
+          ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.ANTHROPIC_VERTEX_PROJECT_ID }}
+          CLOUD_ML_REGION: ${{ secrets.CLOUD_ML_REGION }}
diff --git a/.github/workflows/review.yml b/.github/workflows/review.yml
@@ -6,9 +6,19 @@ on:
 
 jobs:
   review:
+    if: github.actor != 'dependabot[bot]'
     uses: ./.github/workflows/claude-code-review.yml
     secrets:
       GCP_WORKLOAD_IDENTITY_PROVIDER: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
       GCP_SERVICE_ACCOUNT: ${{ secrets.GCP_SERVICE_ACCOUNT }}
       ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.ANTHROPIC_VERTEX_PROJECT_ID }}
       CLOUD_ML_REGION: ${{ secrets.CLOUD_ML_REGION }}
+
+  review-dependency-bump:
+    if: github.actor == 'dependabot[bot]'
+    uses: ./.github/workflows/claude-code-dependency-review.yml
+    secrets:
+      GCP_WORKLOAD_IDENTITY_PROVIDER: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+      GCP_SERVICE_ACCOUNT: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+      ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.ANTHROPIC_VERTEX_PROJECT_ID }}
+      CLOUD_ML_REGION: ${{ secrets.CLOUD_ML_REGION }}
