Configuration options for dependency updates

Detailed information for all the options you can use to customize how GitHub Dependabot maintains your repositories.

People with write permissions to a repository can configure GitHub Dependabot for the repository.

In this article

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.

Note: GitHub Dependabot version updates are currently in beta and subject to change. To use the beta feature, check in a configuration file to tell GitHub Dependabot which dependencies to maintain for you. For details, see "Enabling and disabling version updates."

About the dependabot.yml file

The GitHub Dependabot configuration file, dependabot.yml, uses YAML syntax. If you're new to YAML and want to learn more, see "Learn YAML in five minutes."

You must store this file in the .github directory of your repository. When you add or update the dependabot.yml file, this triggers an immediate check for version updates. Any options that also affect security updates are used the next time a security alert triggers a pull request with for security update. For more information, see "Enabling and disabling version updates" and "Configuring GitHub Dependabot security updates."

Configuration options for dependabot.yml

The dependabot.yml file must start with version: 2 followed by an array of updates.

OptionRequiredDescription
package-ecosystemXPackage manager to use
directoryXLocation of package manifests
schedule.intervalXHow often to check for updates
allowCustomize which updates are allowed
assigneesAssignees to set on pull requests
commit-messageCommit message preferences
ignoreIgnore certain dependencies or versions
labelsLabels to set on pull requests
milestoneMilestone to set on pull requests
open-pull-requests-limitLimit number of open pull requests for version updates
pull-request-branch-name.separatorChange separator for pull request branch names
rebase-strategyDisable automatic rebasing
reviewersReviewers to set on pull requests
schedule.dayDay of week to check for updates
schedule.timeTime of day to check for updates (hh:mm)
schedule.timezoneTimezone for time of day (zone identifier)
target-branchBranch to create pull requests against
vendorUpdate vendored or cached dependencies
versioning-strategyHow to update manifest version requirements

These options fit broadly into the following categories.

In addition, the open-pull-requests-limit option changes the maximum number of pull requests for version updates that GitHub Dependabot can open.

Note: Some of these configuration options may also affect pull requests raised for security updates of vulnerable package manifests.

Security updates are raised for vulnerable package manifests only on the default branch. When configuration options are set for the same branch (true unless you use target-branch), and specify a package-ecosystem and directory for the vulnerable manifest, then pull requests for security updates use relevant options.

In general, security updates use any configuration options that affect pull requests, for example, adding metadata or changing their behavior. For more information about security updates, see "Configuring GitHub Dependabot security updates."

package-ecosystem

Required You add one package-ecosystem element for each package manager that you want Dependabot to monitor for new versions. The repository must also contain a dependency manifest or lock file for each of these package managers. If you want to enable vendoring for a package manager that supports it, the vendored dependencies must be located in the required directory. For more information, see vendor below.

Package managerSupports vendoring
Bundler: bundlerX
Cargo: cargo
Composer: composer
Docker: docker
Elm: elm
git submodule: gitsubmodule
GitHub Actions: github-actions
Go modules: gomodX
Gradle: gradle
Maven: maven
Mix: mix
npm: npm
NuGet: nuget
pip: pip
Terraform: terraform

Note: Dependabot also supports the following package managers:

-yarn (v1 only) (specify npm)

-pipenv, pip-compile, and poetry (specify pip)

For example, if you use poetry to manage your Python dependencies and want Dependabot to monitor your dependency manifest file for new versions, use package-ecosystem: "pip" in your dependabot.yml file.

# Basic set up for three package managers

version: 2
updates:

  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"

  # Maintain dependencies for npm
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"

  # Maintain dependencies for Composer
  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"

directory

Required You must define the location of the package manifests for each package manager (for example, the package.json or Gemfile). You define the directory relative to the root of the repository for all ecosystems except GitHub Actions. For GitHub Actions, set the directory to / to check for workflow files in .github/workflows.

# Specify location of manifest files for each package manager

version: 2
updates:
  - package-ecosystem: "composer"
    # Files stored in repository root
    directory: "/"
    schedule:
      interval: "daily"

  - package-ecosystem: "npm"
    # Files stored in `app` directory
    directory: "/app"
    schedule:
      interval: "daily"

  - package-ecosystem: "github-actions"
    # Workflow files stored in the
    # default location of `.github/workflows`
    directory: "/"
    schedule:
      interval: "daily"

schedule.interval

Required You must define how often to check for new versions and raise pull requests for version updates to each package manager. By default, this is at 5am UTC. To modify this, use schedule.time and schedule.timezone.

  • daily—runs on every weekday, Monday to Friday.
  • weekly—runs once each week. By default, this is on Monday. To modify this, use schedule.day.
  • monthly—runs once each month. This is on the first day of the month.
# Set update schedule for each package manager

version: 2
updates:

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      # Check for updates to GitHub Actions every weekday
      interval: "daily"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      # Check for updates managed by Composer once a week
      interval: "weekly"

allow

By default all dependencies that are explicitly defined in a manifest or lock file are kept up to date. You can use allow and ignore to customize which dependencies to maintain with version updates. GitHub Dependabot checks for all allowed dependencies and then filters out any ignored dependencies or versions. So a dependency that is matched by both an allow and an ignore will be ignored.

Use the allow option to customize which dependencies are updated. This has no impact on security updates for vulnerable dependencies. You can use the following options:

  • dependency-name—use to allow updates for dependencies with matching names, optionally using * to match zero or more characters. For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.

  • dependency-type—use to allow updates for dependencies of specific types.

    Dependency typesSupported by package managersAllow updates
    directAllAll explicitly defined dependencies.
    indirectbundler, pip, composer, cargoDependencies of direct dependencies (also known as sub-dependencies, or transient dependencies).
    allAllAll explicitly defined dependencies. For bundler, pip, composer, cargo, also the dependencies of direct dependencies.
    productionbundler, composer, mix, maven, npm, pipOnly dependencies in the "Product dependency group".
    developmentbundler, composer, mix, maven, npm, pipOnly dependencies in the "Development dependency group".
# Customizing the dependencies to maintain with `allow`

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow updates for Lodash
      - dependency-name: "lodash"
      # Allow updates for React and any packages starting "react"
      - dependency-name: "react*"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow both direct and indirect updates for all packages
      - dependency-type: "all"

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow only direct updates for
      # Django and any packages starting "django"
      - dependency-name: "django*"
        dependency-type: "direct"
      # Allow only production updates for Sphinx
      - dependency-name: "sphinx"
        dependency-type: "production"

assignees

Use assignees to specify individual assignees for all pull requests raised for a package manager.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Specify assignees for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Add assignees
    assignees:
      - "octocat"

commit-message

By default, GitHub Dependabot attempts to detect your commit message preferences and use similar patterns. Use the commit-message option to specify your preferences explicitly.

Supported options

  • prefix specifies a prefix for all commit messages.
  • prefix-development specifies a separate prefix for all commit messages that update dependencies in the Development dependency group. When you specify a value for this option, the prefix is used only for updates to dependencies in the Production dependency group. This is supported by: bundler, composer, mix, maven, npm, and pip.
  • include: "scope" specifies that any prefix is followed by a list of the dependencies updated in the commit.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Customizing commit messages

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    commit-message:
      # Prefix all commit messages with "npm"
      prefix: "npm"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    # Prefix all commit messages with "Composer"
    # include a list of updated dependencies
    commit-message:
      prefix: "Composer"
      include: "scope"

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Include a list of updated dependencies
    # with a prefix determined by the dependency group
    commit-message:
      prefix: "pip prod"
      prefix-development: "pip dev"
      include: "scope"

ignore

Warning: Before you add an ignore option to the dependabot.yml configuration file, check whether the repository already has any ignore preferences (created using the @dependabot ignore commands). When you add an ignore option to the dependabot.yml configuration file, this overwrites any ignore preferences stored centrally for that package manager, branch, and directory.

This affects both security and version updates.

Checking for existing ignore preferences

Before you add an ignore option to the configuration file, check whether you've previously used any of the @dependabot ignore commands on a security update or version update pull request. GitHub Dependabot stores these preferences for each package manager centrally and this information is overwritten by the ignore option. For more information about the @dependabot ignore commands, see "Managing pull requests for dependency updates."

You can check whether a repository has stored preferences by searching the repository for "@dependabot ignore" in:comments. If you review any pull requests in the results, you can decide whether or not to specify those ignored dependencies or versions in the configuration file.

Specifying dependencies and versions to ignore

By default all dependencies that are explicitly defined in a manifest or lock file are kept up to date. You can use allow and ignore to customize which dependencies to maintain with version updates. GitHub Dependabot checks for all allowed dependencies and then filters out any ignored dependencies or versions. So a dependency that is matched by both an allow and an ignore will be ignored.

You can use the ignore option to customize which dependencies are updated. The ignore option supports the following options.

  • dependency-name—use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters. For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.
  • versions—use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager (for example: ^1.0.0 for npm, or ~> 2.0 for Bundler).

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Customizing the dependencies to maintain with `ignore`

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    ignore:
      - dependency-name: "express"
        # For Express, ignore all updates for version 4 and 5
        versions: ["4.x", "5.x"]
        # For Loadash, ignore all updates
      - dependency-name: "loadash"

Note: GitHub Dependabot version updates can't run version updates for any dependencies in manifests containing private git dependencies or private git registries, even if you add the private dependencies to the ignore option of your configuration file. For more information, see "About GitHub Dependabot version updates."

labels

By default, GitHub Dependabot raises all pull requests with the dependencies label. If more than one package manager is defined, Dependabot includes an additional label on each pull request. This indicates which language or ecosystem the pull request will update, for example: java for Gradle updates and submodules for git submodule updates. GitHub Dependabot creates these default labels automatically, as necessary in your repository.

Use labels to override the default labels and specify alternative labels for all pull requests raised for a package manager. If any of these labels is not defined in the repository, it is ignored. To disable all labels, including the default labels, use labels: [ ].

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Specify labels for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Specify labels for npm pull requests
    labels:
      - "npm"
      - "dependencies"

milestone

Use milestone to associate all pull requests raised for a package manager with a milestone. You need to specify the numeric identifier of the milestone and not its label. If you view a milestone, the final part of the page URL, after milestone, is the identifier. For example: https://github.com/<org>/<repo>/milestone/3.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Specify a milestone for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Associate pull requests with milestone "4"
    milestone: 4

open-pull-requests-limit

By default, GitHub Dependabot opens a maximum of five pull requests for version updates. Once there are five open pull requests, new requests are blocked until you merge or close some of the open requests. Use open-pull-requests-limit to change this limit. This also provides a simple way to temporarily disable version updates for a package manager.

This option has no impact on security updates, which have a separate, internal limit of ten open pull requests.

# Changing the number of open pull requests allowed

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Disable version updates for npm dependencies
    open-pull-requests-limit: 0

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Allow up to 10 open pull requests for pip dependencies
    open-pull-requests-limit: 10

pull-request-branch-name.separator

GitHub Dependabot generates a branch for each pull request. Each branch name includes dependabot, and the package manager and dependency that are updated. By default, these parts are separated by a / symbol, for example: dependabot/npm_and_yarn/next_js/acorn-6.4.1.

Use pull-request-branch-name.separator to specify a different separator. This can be one of: "-", _ or /. The hyphen symbol must be quoted because otherwise it's interpreted as starting an empty YAML list.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Specifying a different separator for branch names

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    pull-request-branch-name:
      # Separate sections of the branch name with a hyphen
      # for example, `dependabot-npm_and_yarn-next_js-acorn-6.4.1`
      separator: "-"

rebase-strategy

By default, GitHub Dependabot automatically rebases open pull requests when it detects conflicts. Use rebase-strategy to disable this behavior.

Available rebase strategies

  • disabled to disable automatic rebasing.
  • auto to use the default behavior and rebase open pull requests when conflicts are detected.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Disabling automatic rebasing

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Disable rebasing for npm pull requests
    rebase-strategy: "disabled"

reviewers

Use reviewers to specify individual reviewers or teams of reviewers for all pull requests raised for a package manager. You must use the full team name, including the organization, as if you were @mentioning the team.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

# Specify reviewers for pull requests

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Add reviewers
    reviewers:
      - "octocat"
      - "my-username"
      - "my-org/python-team"

schedule.day

When you set a weekly update schedule, by default, GitHub Dependabot checks for new versions on Monday at 05:00 UTC. Use schedule.day to specify an alternative day to check for updates.

Supported values

  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
  • sunday
# Specify the day for weekly checks

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      # Check for npm updates on Sundays
      day: "sunday"

schedule.time

By default, GitHub Dependabot checks for new versions at 05:00 UTC. Use schedule.time to specify an alternative time of day to check for updates (format: hh:mm).

# Set a time for checks
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
      # Check for npm updates at 9am UTC
      time: "09:00"

schedule.timezone

By default, GitHub Dependabot checks for new versions at 05:00 UTC. Use schedule.timezone to specify an alternative time zone. The time zone identifier must be from the Time Zone database maintained by iana. For more information, see List of tz database time zones.

# Specify the timezone for checks

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
      time: "09:00"
      # Use Japan Standard Time (UTC +09:00)
      timezone: "Asia/Tokyo"

target-branch

By default, GitHub Dependabot checks for manifest files on the default branch and raises pull requests for version updates against this branch. Use target-branch to specify a different branch for manifest files and for pull requests. When you use this option, the settings for this package manager will no longer affect any pull requests raised for security updates.

# Specify a non-default branch for pull requests for pip

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Raise pull requests for version updates
    # to pip against the `develop` branch
    target-branch: "develop"
    # Labels on pull requests for version updates only
    labels:
      - "pip dependencies"

  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      # Check for npm updates on Sundays
      day: "sunday"
    # Labels on pull requests for security and version updates
    labels:
      - "npm dependencies"

vendor

Use the vendor option to tell Dependabot to vendor dependencies when updating them.

# Configure version updates for both dependencies defined in manifests and vendored dependencies

version: 2
updates:
  - package-ecosystem: "bundler"
    # Raise pull requests to update vendored dependencies that are checked in to the repository
    vendor: true
    directory: "/"
    schedule:
      interval: "weekly"

Dependabot only updates the vendored dependencies located in specific directories in a repository.

Package managerRequired file path for vendored dependenciesMore information
bundlerThe dependencies must be in the vendor/cache directory.
Other file paths are not supported.
bundle cache documentation
gomodNo path requirement (dependencies are usually located in the vendor directory)go mod vendor documentation

versioning-strategy

When GitHub Dependabot edits a manifest file to update a version, it uses the following overall strategies:

  • For apps, the version requirements are increased, for example: npm, pip and Composer.
  • For libraries, the range of versions is widened, for example: Bundler and Cargo.

Use the versioning-strategy option to change this behavior for supported package managers.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

Available update strategies

OptionSupported byAction
lockfile-onlybundler, cargo, composer, mix, npm, pipOnly create pull requests to update lockfiles updates. Ignore any new versions that would require package manifest changes.
autobundler, cargo, composer, mix, npm, pipFollow the default strategy described above.
widencomposer, npmRelax the version requirement to include both the new and old version, when possible.
increasebundler, composer, npmAlways increase the version requirement to match the new version.
increase-if-necessarybundler, composer, npmIncrease the version requirement only when required by the new version.
# Customizing the manifest version strategy

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Update the npm manifest file to relax
    # the version requirements
    versioning-strategy: widen

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    # Increase the version requirements for Composer
    # only when required
    versioning-strategy: increase-if-necessary

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Only allow updates to the lockfile for pip and
    # ignore any version updates that affect the manifest
    versioning-strategy: lockfile-only

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.