Dependabot for Dependency Management

GitHub Dependabot automatically opens pull requests to keep your project's dependencies up to date and free of known vulnerabilities. Dependabot works the same way for ASF repositories as it does for any other GitHub repository; there is nothing ASF-specific about its configuration.

Note: All repositories using GitHub Actions must have Dependabot (or Renovate) enabled for the github-actions ecosystem. See the GitHub Actions Policy for details.

Getting started¶

Follow the Dependabot Quickstart Guide to enable Dependabot for your repository.

In short, create a .github/dependabot.yml file in your repository. The file must start with version: 2 and contain an updates list with one entry per package ecosystem your project uses.

A minimal example:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

Identify your ecosystems¶

Dependabot supports a wide range of package ecosystems. Look at which dependency files exist in your repository and add a package-ecosystem entry for each one. Many projects use several ecosystems at once (for example, a Python project may have pip for dependencies, github-actions for CI, and docker for container images). Common ecosystems include:

Ecosystem	Manifest files	`package-ecosystem` value
GitHub Actions	`.github/workflows/*.yml`	`github-actions`
Maven	`pom.xml`	`maven`
Gradle	`build.gradle`, `build.gradle.kts`	`gradle`
npm	`package.json`	`npm`
pip	`requirements.txt`, `setup.py`, `pyproject.toml`	`pip`
uv	`uv.lock`	`uv`
Go modules	`go.mod`	`gomod`
Cargo (Rust)	`Cargo.toml`	`cargo`
Bundler (Ruby)	`Gemfile`	`bundler`
Composer (PHP)	`composer.json`	`composer`
NuGet (.NET)	`.csproj`, `.fsproj`	`nuget`
Docker	`Dockerfile`	`docker`
Terraform	`*.tf`	`terraform`

For the full list of supported ecosystems, see the Dependabot configuration reference.

Set the directory field to the location of the manifest file relative to the repository root (for example, "/" or "/frontend"). For GitHub Actions, use "/" (Dependabot knows to look in .github/workflows).

Recommendations¶

Choose an update schedule that fits your project¶

The right update frequency depends on the size of your project, the number of dependencies, and how often you release. Some projects run Dependabot daily, others weekly or quarterly — there is no single correct answer. Large, frequently-released projects (for example, Apache Airflow ships ~100 distributions every two weeks) benefit from updating as often as possible and bumping to the highest available versions each time. As the saying goes, "if something is painful, do it more frequently."

A weekly schedule is a reasonable starting point for many projects, but smaller or less frequently released projects may prefer monthly or even quarterly reviews. If your project has many dependencies, use groups to combine related updates into a single pull request:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      all-dependencies:
        patterns:
          - "*"

You can also split groups by update type or dependency kind:

    groups:
      minor-and-patch:
        update-types:
          - "minor"
          - "patch"
      major:
        update-types:
          - "major"

Unless you say otherwise, a group covers version updates only. See Group security updates below to batch security fixes the same way.

Group security updates¶

Every project repository is now scanned by GitHub's Dependabot alerts and by the scanners that downstream users and their employers run against ASF project releases, so we now see many more security updates than we used to. Projects rush to fix what the scanners report as quickly as they can.

That response has a cost: by default, a groups block applies only to version updates, so security updates open one pull request per alert, each with a full CI run behind it. This can add hundreds of builds into the shared GitHub Actions queue.

A group with applies-to: security-updates set collects all outstanding security fixes for that group into one pull request:

version: 2
updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      # One PR for the routine version bumps
      maven-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      # One PR for all outstanding security fixes
      maven-security:
        applies-to: security-updates
        patterns:
          - "*"

When applies-to is omitted, the group defaults to version-updates, which is why a configuration that groups version updates can still produce a flood of individual security PRs.

Grouping is a trade-off: a grouped pull request is all-or-nothing, so one update in the batch that breaks your build holds up the rest of the fixes in it. If your project needs to land a critical fix in isolation, narrow the group's patterns to leave that dependency out, or keep a separate group for the dependencies you want to review one at a time.

For the full syntax, see the Dependabot groups configuration reference.

Use a cooldown period¶

A cooldown delays Dependabot from proposing a new dependency version until it has been published for a minimum number of days. This gives the community time to discover issues with a release — including compromised packages — before your project adopts it. See Why you should use dependency cooldowns for background on the security rationale.

A 4-day cooldown is a good default:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4

Note: Cooldowns apply only to version updates, not to security updates, so critical fixes are never delayed.

Ignore incompatible versions¶

Dependabot does not account for the language or runtime version your project targets. It may propose dependency updates that require a newer version of Java, Python, or another runtime than your project supports. Use the ignore option to prevent Dependabot from proposing versions you cannot use.

For example, if your project still targets Java 8 and a library released version 5.x that requires Java 11+, you can cap updates to the 4.x line:

  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "com.example:some-library"
        versions: [">=5.0.0"]

You can also ignore all major version bumps for a dependency while still receiving minor and patch updates:

    ignore:
      - dependency-name: "com.example:some-library"
        update-types: ["version-update:semver-major"]

Similarly, if a Python package has dropped support for your Python version:

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "some-package"
        versions: [">=3.0"]

For full details on the ignore syntax, see the Dependabot ignore configuration reference.

Full example¶

Below is a complete example for a project that uses GitHub Actions, Maven, npm, pip, and uv:

version: 2
updates:
  # Keep GitHub Actions up to date
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4
    groups:
      actions-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      actions-security:
        applies-to: security-updates
        patterns:
          - "*"

  # Keep Maven dependencies up to date
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4
    groups:
      maven-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      maven-security:
        applies-to: security-updates
        patterns:
          - "*"

  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/frontend"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4
    groups:
      npm-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      npm-security:
        applies-to: security-updates
        patterns:
          - "*"

  # Keep pip dependencies up to date
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4
    groups:
      pip-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      pip-security:
        applies-to: security-updates
        patterns:
          - "*"

  # Keep uv dependencies up to date
  - package-ecosystem: "uv"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 4
    groups:
      uv-dependencies:
        applies-to: version-updates
        patterns:
          - "*"
      uv-security:
        applies-to: security-updates
        patterns:
          - "*"