Dependabot config files

You can configure multiple projects and languages from a file named config.yml. The config.yml file is located in a folder named .dependabot at the root of your repository.

All available configration options are documented below.


Getting started

Add the following file to the root of your repository (on the default branch): .dependabot/config.yml (see working example).

If you haven't done so already, you'll first need to sign up and grant Dependabot access to your repositories.

Example config.yml files

With only required options

version: 1
update_configs:
  # Keep package.json (& lockfiles) up to date as soon as
  # new versions are published to the npm registry
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "live"
  # Keep Dockerfile up to date, batching pull requests weekly
  - package_manager: "docker"
    directory: "/"
    update_schedule: "weekly"

With default labels and reviewers

version: 1
update_configs:
  # Update your Gemfile (& lockfiles) as soon as
  # new versions are published to the RubyGems registry
  - package_manager: "ruby:bundler"
    directory: "/"
    update_schedule: "live"

    # Apply default reviewer and label to created
    # pull requests
    default_reviewers:
      - "github-username"
    default_labels:
      - "label-name"

Config file validator

Check your config file using our online tool:

Validate your .dependabot/config.yml file

Dependabot will create an issue on your repository if there are any problems parsing the config file (make sure you've got GitHub Issues enabled to hear about any problems).


Available configuration options

The config file must start with version: 1 followed by an array of update_configs.

Option Required Description
package_manager yes What package manager to use
directory yes Where to look for package manifests
update_schedule yes How often to check for updates
target_branch no Branch to create pull requests against
default_reviewers no Reviewers to set on pull requests
default_assignees no Assignees to set on pull requests
default_labels no Labels to set on pull requests
default_milestone no Milestone to set on pull requests
allowed_updates no Limit which updates are allowed
ignored_updates no Ignore certain dependencies or versions
automerged_updates no Updates that should be merged automatically
version_requirement_updates no How to update manifest version requirements
commit_message no Commit message preferences

package_manager (required)

Supported package managers:

  • javascript
  • ruby:bundler
  • php:composer
  • python
  • go:modules
  • go:dep
  • java:maven
  • java:gradle
  • dotnet:nuget
  • rust:cargo
  • elixir:hex
  • docker
  • terraform
  • submodules
  • elm

Example: package manager

version: 1
update_configs:
  - package_manager: "submodules"
    directory: "/"
    update_schedule: "daily"

directory (required)

Where to look for package manifests (e.g. your package.json or Gemfile). The directory is relative to the repository's root.

Example: directory

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/app"
    update_schedule: "daily"

update_schedule (required)

How often to check for non-security updates and when to create pull requests. Security updates are always created as soon as possible (i.e., "live").

Available schedules

  • live

    • Only supported by the following package managers

      • javascript
      • ruby:bundler
      • python
      • php:composer
      • dotnet:nuget
      • rust:cargo
      • elixir:hex
  • daily

    • Only runs on weekdays (Monday to Friday)
  • weekly
  • monthly

For daily and weekly schedules you can also specify the run day and time in your dashboard account settings.

Example: update schedule

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "monthly"

target_branch

Branch to create pull requests against.

By default your repository's default branch is used.

Example: target branch

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    target_branch: "develop"

default_reviewers

Reviewers to set on update pull requests.

Example: default reviewers

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    default_reviewers:
      - "github_username1"
      - "github_username2"

default_assignees

Assignees to set on update pull requests.

Example: default assignees

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    default_assignees:
      - "github_username1"
      - "github_username2"

default_labels

Labels to set on update pull requests.

By default dependencies is used.

Example: default labels

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    default_labels:
      - "dependencies"
      - "dependabot"

default_milestone

Milestone to set on dependency update pull requests.

Specified using the milestone number - you can find this in the URL when looking at details of a milestone in GitHub.

Example: default milestone

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    default_milestone: 12

allowed_updates

Limit which updates are allowed.

By default all direct/top-level dependencies are kept up to date (indirect/sub-dependencies are only updated if they include security fixes).

Example: only allow security updates

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    allowed_updates:
      - match:
          update_type: "security"

Example: updates matching on dependency name or security updates

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    allowed_updates:
      - match:
          update_type: "security"
      - match:
          dependency_name: "lodash"
      - match:
          # Wildcards match unlimited arbitrary characters (or none)
          dependency_name: "react*"

Example: update matching direct/top-level dependencies on name

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    allowed_updates:
      - match:
          dependency_name: "react"
          dependency_type: "direct"

Example: all updates including indirect/sub-dependencies

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    allowed_updates:
      - match:
          # Only includes indirect (aka transient/sub-dependencies) for
          # supported package managers: ruby:bundler, python, go:modules,
          #                             php:composer, rust:cargo
          update_type: "all"

Example: updates matching dependency type and update type

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    allowed_updates:
      - match:
          dependency_type: "development"
          # Supported dependency types:
          # - "development"
          #   Development dependency group (supported by some package managers)
          # - "production"
          #   Production dependency group (supported by some package managers)
          # - "direct"
          #   Direct/top-level dependencies
          # - "indirect"
          #   Indirect/transient/sub-dependencies
          # - "all"
          update_type: "all"
          # Supported update types:
          # - "security"
          # - "all"
      - match:
          dependency_type: "production"
          update_type: "security"

ignored_updates

By default no updates are ignored.

Example: ignored updates

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    ignored_updates:
      - match:
          dependency_name: "express"
          # The version_requirement specifies the versions to ignore.
          # The range format is specific to the package manager
          # (e.g., ^1.0.0 for JS, or ~> 2.0 for Ruby).
          version_requirement: "4.x"
      - match:
          # Wildcards match unlimited arbitrary characters (or none)
          dependency_name: "aws*"

automerged_updates

Automerged updates must be enabled at the account level (from account settings in your dashboard) before they can be configured on a project.

Specify which update pull requests should be merged automatically.

By default no updates are automerged.

For all of the options below Dependabot will wait until all your status checks pass before merging. You can also set working hours for automerging in your dashboard account settings.

Example: automerge based on dependency type

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    automerged_updates:
      - match:
          dependency_type: "development"
          # Supported dependency types:
          # - "development"
          # - "production"
          # - "all"
          update_type: "all"
          # Supported updates to automerge:
          # - "security:patch"
          #   SemVer patch update that fixes a known security vulnerability
          # - "semver:patch"
          #   SemVer patch update, e.g. > 1.x && 1.0.1 to 1.0.3
          # - "semver:minor"
          #   SemVer minor update, e.g. > 1.x && 2.1.4 to 2.3.1
          # - "in_range"
          #   matching the version requirement in your package manifest
          # - "all"
      - match:
          dependency_type: "production"
          update_type: "semver:patch"

Example: automerge based on dependency name

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    automerged_updates:
      - match:
          dependency_name: "puma"
          update_type: "semver:minor"
      - match:
          # Wildcards match unlimited arbitrary characters (or none)
          dependency_name: "rspec*"

version_requirement_updates

Specify how Dependabot should update your package manifest (e.g. package.json, Gemfile etc), as opposed to your lockfile.

By default, version requirements are increased if it's an app and the range widened if it's a library (widen_ranges is used for javascript ,python, php:composer, go:dep and increase_versions_if_necessary is used for ruby:bundler and rust:cargo).

Library detection varies dependeing on the package manager but usually means there is no lockfile or the manifest has a library type set.

Available update strategies

  • off (Only lockfile updates, ignoring updates that require package manifest changes)
  • auto: (Increase versions if an app, widen ranges if a library)

    • Only supported by the following package managers

      • javascript
      • ruby:bundler
      • go:dep
      • python
      • php:composer
      • rust:cargo
      • elixir:hex
  • widen_ranges: (Relax the version requirement to include both the new and old version when possible)

    • Only supported by the following package managers

      • javascript
      • php:composer
      • go:dep
  • increase_versions (Always increase the version requirement to match the new version)

    • Only supported by the following package managers

      • javascript
      • ruby:bundler
      • php:composer
      • go:dep
  • increase_versions_if_necessary (Increase the version requirement only when required by the new version)

    • Only supported by the following package managers

      • javascript
      • ruby:bundler
      • php:composer

commit_message

Preferences for the format of Dependabot's commit messages and pull request titles.

By default, Dependabot will attempt to detect your commit message preferences and use those.

Example: custom commit prefix

With this setup, all Dependabot commits will be prefixed with chore:.

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    commit_message:
      prefix: "chore"

Example: custom commit prefix with scope

With this setup, Dependabot commits will be prefixed with chore(deps):.

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    commit_message:
      prefix: "chore"
      include_scope: true

Example: custom commit prefix for prod and development dependencies

With this setup, Dependabot commits for production dependencies will be prefixed with fix(deps):, whilst commits for development dependencies will use chore(deps-dev):.

version: 1
update_configs:
  - package_manager: "javascript"
    directory: "/"
    update_schedule: "daily"
    commit_message:
      prefix: "fix"
      prefix_development: "chore"
      include_scope: true