Dependabot

---
name: dependabot
description: "Expert agent for GitHub Dependabot. Covers dependabot.yml configuration, security alerts, version updates, auto-merge, grouped updates, private registries, and GitHub Advanced Security integration. WHEN: \"Dependabot\", \"dependabot.yml\", \"GitHub security alerts\", \"Dependabot alerts\", \"Dependabot version updates\", \"Dependabot security updates\", \"auto-merge dependencies\", \"GitHub dependency review\"."
license: MIT
---

# Dependabot

This skill covers GitHub Dependabot, GitHub's native dependency management and security alerting system. Dependabot is built into GitHub and requires no separate installation for public repositories or GitHub Advanced Security customers.

## How to Approach Tasks

1. **Identify the Dependabot feature:**
   - **Security alerts** -- Alerts for known vulnerabilities in your dependencies (automatic, no config needed)
   - **Security updates** -- Auto-PRs to fix security alerts (automatic, can be enabled)
   - **Version updates** -- Scheduled PRs to update dependencies to latest versions (requires `dependabot.yml`)
2. **Identify the ecosystem** -- Configuration varies by package manager.
3. **Identify the concern** -- PR management, auto-merge rules, private registry access, grouping.

## Dependabot Features Overview

```
Dependabot
├── Security Alerts        ← Automatic on all GitHub repos (public + GAS private)
│   └── Alerts for CVEs in your dependency graph
│
├── Security Updates       ← Automatic PRs to fix security alerts
│   └── Enabled via repository settings or dependabot.yml
│
└── Version Updates        ← Scheduled PRs to keep deps up-to-date
    └── Configured via .github/dependabot.yml
```

---

## dependabot.yml Configuration

Location: `.github/dependabot.yml` in your repository.

### Minimal Configuration

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"               # Root of npm packages
    schedule:
      interval: "weekly"         # daily | weekly | monthly
```

### Full Configuration Reference

```yaml
version: 2

updates:
  # npm / yarn / pnpm
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"              # monday-sunday (for weekly)
      time: "09:00"              # HH:MM UTC
      timezone: "America/New_York"
    
    # PR management
    open-pull-requests-limit: 10   # Max open PRs (default: 5)
    target-branch: "develop"       # Branch to target (default: default branch)
    
    # Labels and assignees
    labels:
      - "dependencies"
      - "security"
    reviewers:
      - "security-team"
    assignees:
      - "platform-team"
    
    # Commit message format
    commit-message:
      prefix: "fix"
      prefix-development: "chore"
      include: "scope"           # Include package name in commit message
    
    # Versioning strategy
    versioning-strategy: auto    # auto | lockfile-only | widen | increase | increase-if-necessary
    
    # Grouping (group multiple updates into one PR)
    groups:
      production-dependencies:
        dependency-type: "production"
        update-types:
          - "minor"
          - "patch"
      dev-dependencies:
        dependency-type: "development"
    
    # Ignore specific packages or versions
    ignore:
      - dependency-name: "lodash"
        versions: ["4.x"]        # Ignore lodash 4.x updates
      - dependency-name: "express"
        update-types: ["version-update:semver-major"]  # Ignore major updates only
    
    # Allow only specific update types
    allow:
      - dependency-type: "direct"   # Only update direct dependencies
        update-types:
          - "version-update:semver-patch"
          - "version-update:semver-minor"
    
    # Private registry configuration
    registries: "*"   # Use all registries defined in top-level registries section

  # Python / pip
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    
  # Maven
  - package-ecosystem: "maven"
    directory: "/backend"
    schedule:
      interval: "weekly"
  
  # Gradle
  - package-ecosystem: "gradle"
    directory: "/"
    schedule:
      interval: "weekly"

  # .NET / NuGet
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "monthly"
  
  # Go modules
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
  
  # Docker
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
  
  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
  
  # Terraform
  - package-ecosystem: "terraform"
    directory: "/infrastructure"
    schedule:
      interval: "monthly"

# Private registry configurations
registries:
  npm-private:
    type: npm-registry
    url: https://npm.pkg.github.com
    token: ${{secrets.GITHUB_TOKEN}}
  
  maven-nexus:
    type: maven-repository
    url: https://nexus.example.com/repository/maven-releases/
    username: ${{secrets.NEXUS_USERNAME}}
    password: ${{secrets.NEXUS_PASSWORD}}
  
  docker-acr:
    type: docker-registry
    url: myregistry.azurecr.io
    username: ${{secrets.ACR_USERNAME}}
    password: ${{secrets.ACR_PASSWORD}}
```

### Supported Package Ecosystems

| `package-ecosystem` | Language/Tool |
|---|---|
| `bundler` | Ruby |
| `cargo` | Rust |
| `composer` | PHP |
| `docker` | Dockerfile |
| `elm` | Elm |
| `github-actions` | GitHub Actions workflows |
| `gitsubmodule` | Git submodules |
| `gomod` | Go |
| `gradle` | Java/Kotlin Gradle |
| `maven` | Java Maven |
| `mix` | Elixir |
| `npm` | JavaScript/TypeScript |
| `nuget` | .NET |
| `pip` | Python |
| `pub` | Dart/Flutter |
| `swift` | Swift |
| `terraform` | Terraform |

---

## Security Alerts

Dependabot Security Alerts are automatic — no `dependabot.yml` configuration needed.

### Enabling Security Alerts

Repository → Settings → Security → Dependabot alerts → Enable

For organization-wide enablement:
Organization Settings → Code security → Dependabot alerts → Enable for all repositories

### Understanding Alert Severity

GitHub uses CVSS to determine alert severity:
- **Critical:** CVSS 9.0-10.0
- **High:** CVSS 7.0-8.9
- **Medium:** CVSS 4.0-6.9
- **Low:** CVSS 0.1-3.9

Alerts are linked to the GitHub Advisory Database (GHSA records).

### Alert States

| State | Meaning |
|---|---|
| Open | Active vulnerability, not fixed |
| Fixed | Resolved by dependency update |
| Dismissed | Manually dismissed with reason |
| Auto-dismissed | Dismissed because vulnerability doesn't affect default branch |

**Dismissal reasons:**
- Tolerable risk
- False positive
- No bandwidth to fix
- Vulnerable code is not actually used

### Dependency Review

GitHub Dependency Review (available with GitHub Advanced Security) shows security impact of dependency changes in PRs:

```yaml
# .github/workflows/dependency-review.yml
name: Dependency Review
on: [pull_request]

jobs:
  dependency-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/dependency-review-action@v4
        with:
          fail-on-severity: high
          deny-licenses: GPL-2.0, AGPL-3.0
          # Optionally allow specific CVEs
          allow-ghsas: GHSA-xxxx-xxxx-xxxx
```

This action:
- Blocks PRs that introduce new high/critical vulnerabilities
- Can block PRs introducing disallowed licenses
- Shows a diff of dependency changes in the PR

---

## Security Updates (Auto-Fix PRs)

Dependabot Security Updates automatically creates PRs to fix security alerts.

### Enabling Security Updates

Repository → Settings → Security → Dependabot security updates → Enable

or in `dependabot.yml` (security updates cannot be configured here, only enabled/disabled via settings).

### Security Update PR Behavior

- Created automatically when a security alert is published for a dependency you use
- Targets the minimum version upgrade that resolves the vulnerability
- One PR per vulnerability (not per dependency)
- PR title: "Bump lodash from 4.17.20 to 4.17.21"
- PR body includes: CVE details, CVSS score, vulnerability description, changelog

---

## Auto-Merge Configuration

Auto-merge is not a Dependabot feature directly — it's a GitHub feature that Dependabot PRs can use.

### Method 1: GitHub Actions Auto-Merge

```yaml
# .github/workflows/auto-merge-dependabot.yml
name: Auto-merge Dependabot PRs

on: pull_request

permissions:
  pull-requests: write
  contents: write

jobs:
  auto-merge:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]'
    steps:
      - uses: actions/checkout@v4
      
      - name: Get Dependabot metadata
        id: metadata
        uses: dependabot/fetch-metadata@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Auto-merge patch and minor updates
        if: >-
          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
          steps.metadata.outputs.update-type == 'version-update:semver-minor'
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Method 2: Branch Protection + Auto-Merge

1. Enable "Allow auto-merge" in repository settings
2. Require status checks (tests must pass)
3. Dependabot PRs with passing tests auto-merge

### Dependabot Metadata Action

The `dependabot/fetch-metadata` action extracts useful information about the Dependabot PR:

```yaml
- id: metadata
  uses: dependabot/fetch-metadata@v2

# Available outputs:
# steps.metadata.outputs.dependency-names        # e.g., "lodash"
# steps.metadata.outputs.dependency-type         # e.g., "direct:production"
# steps.metadata.outputs.update-type             # e.g., "version-update:semver-patch"
# steps.metadata.outputs.previous-version        # e.g., "4.17.20"
# steps.metadata.outputs.new-version             # e.g., "4.17.21"
# steps.metadata.outputs.ghsa-ids                # GitHub Advisory IDs
# steps.metadata.outputs.cvss                    # CVSS score
# steps.metadata.outputs.compatible-updates      # Whether update is compatible
```

---

## Grouped Updates

Grouping reduces PR noise by combining related updates:

```yaml
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      # Group all AWS SDK updates into one PR
      aws-sdk:
        patterns:
          - "@aws-sdk/*"
      # Group all testing tools
      testing:
        patterns:
          - "jest*"
          - "@testing-library/*"
          - "vitest*"
        update-types:
          - "minor"
          - "patch"
      # All production minor/patch into one PR
      production-minor-patch:
        dependency-type: "production"
        update-types:
          - "minor"
          - "patch"
```

---

## GitHub Advanced Security Integration

**Dependabot + Code Scanning + Secret Scanning = GitHub Advanced Security (GHAS)**

In GHAS:
- Dependabot alerts appear in Security → Dependabot tab
- Code scanning (CodeQL) alerts in Security → Code scanning tab
- Secret scanning alerts in Security → Secret scanning tab
- Unified Security Overview across all repositories in organization

**Security policy (SECURITY.md):**
```markdown
# Security Policy

## Supported Versions
| Version | Supported |
|---------|-----------|
| 2.x     | Yes       |
| 1.x     | No        |

## Reporting a Vulnerability
Please report via GitHub Security Advisories or email security@example.com.
Expected response time: 48 hours.
```

---

## Common Issues

**Dependabot PRs failing CI:**
- New version may have breaking changes — review changelog in PR
- Test the upgrade locally: `npm update package-name`
- Check for peer dependency conflicts

**Dependabot not creating PRs for a package manager:**
- Check `directory` is correct (relative to repo root, starts with `/`)
- Ensure manifest file exists at the specified directory
- Review GitHub Actions logs for Dependabot: Security → Dependabot → Recent update jobs

**Too many Dependabot PRs:**
- Use `groups` to batch related updates
- Increase `schedule.interval` to monthly
- Use `ignore` to skip minor/patch updates you handle manually
- Set `open-pull-requests-limit` lower

**Private registry authentication failing:**
- Verify secret names match exactly what's in `dependabot.yml` (`${{secrets.SECRET_NAME}}`)
- Dependabot uses repository secrets, not environment secrets
- For GitHub Package Registry: use `GITHUB_TOKEN` — ensure correct permissions

**`version-update:semver-major` creates breaking PRs:**
- Add `ignore` rule for major updates on critical packages
- Review major updates manually before merging
- Use `allow` to restrict Dependabot to only patch updates in production