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"

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:
        patterns:
          - "*"

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

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

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

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