Note: Dependabot security and version updates are currently in private beta and subject to change. Please contact your account management team for instructions on enabling Dependabot updates.
Note: Your site administrator must set up Dependabot updates for your GitHub Enterprise Server instance before you can use this feature. For more information, see "Enabling Dependabot for your enterprise."
About the dependabot.yml file
The 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. For more information and an example, see "Configuring Dependabot version updates."
Any options that also affect security updates are used the next time a security alert triggers a pull request for a security update. For more information, see "Configuring Dependabot security updates."
Note: You cannot configure Dependabot alerts using the dependabot.yml file.
The dependabot.yml file has two mandatory top-level keys: version
, and updates
. You can, optionally, include a top-level registries
key. The file must start with version: 2
.
Configuration options for the dependabot.yml file
The top-level updates
key is mandatory. You use it to configure how Dependabot updates the versions or your project's dependencies. Each entry configures the update settings for a particular package manager. You can use the following options.
Option | Required | Security Updates | Version Updates | Description |
---|---|---|---|---|
package-ecosystem | X | X | Package manager to use | |
directory | X | X | Location of package manifests | |
schedule.interval | X | X | How often to check for updates | |
allow | X | X | Customize which updates are allowed | |
assignees | X | X | Assignees to set on pull requests | |
commit-message | X | X | Commit message preferences | |
ignore | X | X | Ignore certain dependencies or versions | |
insecure-external-code-execution | X | Allow or deny code execution in manifest files | ||
labels | X | X | Labels to set on pull requests | |
milestone | X | X | Milestone to set on pull requests | |
open-pull-requests-limit | X | X | Limit number of open pull requests for version updates | |
pull-request-branch-name.separator | X | X | Change separator for pull request branch names | |
rebase-strategy | X | X | Disable automatic rebasing | |
registries | X | Private registries that Dependabot can access | ||
reviewers | X | X | Reviewers to set on pull requests | |
schedule.day | X | Day of week to check for updates | ||
schedule.time | X | Time of day to check for updates (hh:mm) | ||
schedule.timezone | X | Timezone for time of day (zone identifier) | ||
target-branch | X | Branch to create pull requests against | ||
vendor | X | Update vendored or cached dependencies | ||
versioning-strategy | X | X | How to update manifest version requirements |
These options fit broadly into the following categories.
- Essential set up options that you must include in all configurations:
package-ecosystem
,directory
,schedule.interval
. - Options to customize the update schedule:
schedule.time
,schedule.timezone
,schedule.day
. - Options to control which dependencies are updated:
allow
,ignore
,vendor
. - Options to add metadata to pull requests:
reviewers
,assignees
,labels
,milestone
. - Options to change the behavior of the pull requests:
target-branch
,versioning-strategy
,commit-message
,rebase-strategy
,pull-request-branch-name.separator
.
In addition, the open-pull-requests-limit
option changes the maximum number of pull requests for version updates that 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 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.
The following table shows, for each package manager:
- The YAML value to use in the dependabot.yml file
- The supported versions of the package manager
- Whether dependencies in private GitHub repositories or registries are supported
- Whether vendored dependencies are supported
Package manager | YAML value | Supported versions | Private repositories | Private registries | Vendoring |
---|---|---|---|---|---|
Bundler | bundler | v1, v2 | ✓ | ✓ | |
Cargo | cargo | v1 | ✓ | ✓ | |
Composer | composer | v1, v2 | ✓ | ✓ | |
Docker | docker | v1 | ✓ | ✓ | |
Hex | mix | v1 | ✓ | ||
elm-package | elm | v0.19 | ✓ | ✓ | |
git submodule | gitsubmodule | N/A (no version) | ✓ | ✓ | |
GitHub Actions [2] | github-actions | N/A (no version) | ✓ | ✓ | |
Go modules | gomod | v1 | ✓ | ✓ | ✓ |
Gradle [3] | gradle | N/A (no version) | ✓ | ✓ | |
Maven [4] | maven | N/A (no version) | ✓ | ✓ | |
npm | npm | v6, v7, v8 | ✓ | ✓ | |
NuGet | nuget | <= 4.8[5] | ✓ | ✓ | |
pip | pip | v21.1.2 | ✓ | ||
pipenv | pip | <= 2021-05-29 | ✓ | ||
pip-compile | pip | 6.1.0 | ✓ | ||
poetry | pip | v1 | ✓ | ||
Terraform | terraform | >= 0.13, <= 1.3.x | ✓ | ✓ | |
yarn | npm | v1 | ✓ | ✓ |
Tip: For package managers such as pipenv
and poetry
, you need to use the pip
YAML value. 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.
[2] Dependabot only supports updates to GitHub Actions using the GitHub repository syntax, such as actions/checkout@v2. Docker Hub and GitHub Packages Container registry URLs are currently not supported.
[3] Dependabot doesn't run Gradle but supports updates to the following files: build.gradle
, build.gradle.kts
(for Kotlin projects), and files included via the apply
declaration that have dependencies
in the filename. Note that apply
does not support apply to
, recursion, or advanced syntaxes (for example, Kotlin's apply
with mapOf
, filenames defined by property).
[4] Dependabot doesn't run Maven but supports updates to pom.xml
files.
[5] Dependabot doesn't run the NuGet CLI but does support most features up until version 4.8.
# Basic set up for three package managers
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
# Maintain dependencies for npm
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Maintain dependencies for Composer
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
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: "weekly"
- package-ecosystem: "npm"
# Files stored in `app` directory
directory: "/app"
schedule:
interval: "weekly"
- package-ecosystem: "github-actions"
# Workflow files stored in the
# default location of `.github/workflows`
directory: "/"
schedule:
interval: "weekly"
schedule.interval
Required. You must define how often to check for new versions for each package manager. By default, Dependabot randomly assigns a time to apply all the updates in the configuration file. To set a specific time, you can use schedule.time
and schedule.timezone
.
Interval types | Frequency |
---|---|
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"
Note: schedule
defines when Dependabot attempts a new update. However, it's not the only time you may receive pull requests. Updates can be triggered based on changes to your dependabot.yml
file, changes to your manifest file(s) after a failed update, or Dependabot security updates. For more information, see "Frequency of Dependabot pull requests" and "About Dependabot security updates."
allow
By default all dependencies that are explicitly defined in a manifest are kept up to date by Dependabot version updates. In addition, Dependabot security updates also update vulnerable dependencies that are defined in lock files. You can use allow
and ignore
to customize which dependencies to maintain. 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 applies to both version and security updates. 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 thedependency-name
attribute is:groupId:artifactId
, for example:org.kohsuke:github-api
. -
dependency-type
—use to allow updates for dependencies of specific types.Dependency types Supported by package managers Allow updates direct
All All explicitly defined dependencies. indirect
bundler
,pip
,composer
,cargo
Dependencies of direct dependencies (also known as sub-dependencies, or transient dependencies). all
All All explicitly defined dependencies. For bundler
,pip
,composer
,cargo
, also the dependencies of direct dependencies.production
bundler
,composer
,mix
,maven
,npm
,pip
Only dependencies in the "Production dependency group". development
bundler
,composer
,mix
,maven
,npm
,pip
Only dependencies in the "Development dependency group".
# Use `allow` to specify which dependencies to maintain
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
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: "weekly"
allow:
# Allow both direct and indirect updates for all packages
- dependency-type: "all"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
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: "weekly"
# Add assignees
assignees:
- "octocat"
commit-message
By default, Dependabot attempts to detect your commit message preferences and use similar patterns. Use the commit-message
option to specify your preferences explicitly.
Supported options
Note: The prefix
and the prefix-development
options have a 15 character limit.
-
prefix
specifies a prefix for all commit messages. When you specify a prefix for commit messages, GitHub will automatically add a colon between the defined prefix and the commit message provided the defined prefix ends with a letter, number, closing parenthesis, or closing bracket. This means that, for example, if you end the prefix with a whitespace, there will be no colon added between the prefix and the commit message. The code snippet below provides examples of both in the same configuration file. -
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, theprefix
is used only for updates to dependencies in the Production dependency group. This is supported by:bundler
,composer
,mix
,maven
,npm
, andpip
. -
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.
# Customize commit messages
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
commit-message:
# Prefix all commit messages with "npm: "
prefix: "npm"
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
commit-message:
# Prefix all commit messages with "[docker] " (no colon, but a trailing whitespace)
prefix: "[docker] "
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
# Prefix all commit messages with "Composer" plus its scope, that is, a
# list of updated dependencies
commit-message:
prefix: "Composer"
include: "scope"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# 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"
If you use the same configuration as in the example above, bumping the requests
library in the pip
development dependency group will generate a commit message of:
pip dev: bump requests from 1.0.0 to 1.0.1
ignore
By default all dependencies that are explicitly defined in a manifest are kept up to date by Dependabot version updates. In addition, Dependabot security updates also update vulnerable dependencies that are defined in lock files. You can use allow
and ignore
to customize which dependencies to maintain. 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.
Dependencies can be ignored either by adding them to ignore
or by using the @dependabot ignore
command on a pull request opened by Dependabot.
Creating ignore
conditions from @dependabot ignore
Dependencies ignored by using the @dependabot ignore
command are stored centrally for each package manager. If you start ignoring dependencies in the dependabot.yml
file, these existing preferences are considered alongside the ignore
dependencies in the configuration.
You can check whether a repository has stored ignore
preferences by searching the repository for "@dependabot ignore" in:comments
. If you wish to un-ignore a dependency ignored this way, re-open the pull request.
For more information about the @dependabot ignore
commands, see "Managing pull requests for dependency updates."
Specifying dependencies and versions to ignore
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 thedependency-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).update-types
—use to ignore types of updates, such as semvermajor
,minor
, orpatch
updates on version updates (for example:version-update:semver-patch
will ignore patch updates). You can combine this withdependency-name: "*"
to ignore particularupdate-types
for all dependencies. Currently,version-update:semver-major
,version-update:semver-minor
, andversion-update:semver-patch
are the only supported options. Security updates are unaffected by this setting.
If versions
and update-types
are used together, Dependabot will ignore any update in either set.
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.
# Use `ignore` to specify dependencies that should not be updated
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
ignore:
- dependency-name: "express"
# For Express, ignore all updates for version 4 and 5
versions: ["4.x", "5.x"]
# For Lodash, ignore all updates
- dependency-name: "lodash"
# For AWS SDK, ignore all patch updates
- dependency-name: "aws-sdk"
update-types: ["version-update:semver-patch"]
Note: Dependabot can only run version updates on manifest or lock files if it can access all of the dependencies in the file, even if you add inaccessible dependencies to the ignore
option of your configuration file. For more information, see "Managing security and analysis settings for your organization" and "Troubleshooting Dependabot errors."
insecure-external-code-execution
Package managers with the package-ecosystem
values bundler
, mix
, and pip
may execute external code in the manifest as part of the version update process. This might allow a compromised package to steal credentials or gain access to configured registries. When you add a registries
setting within an updates
configuration, Dependabot automatically prevents external code execution, in which case the version update may fail. You can choose to override this behavior and allow external code execution for bundler
, mix
, and pip
package managers by setting insecure-external-code-execution
to allow
.
You can explicitly deny external code execution, irrespective of whether there is a registries
setting for this update configuration, by setting insecure-external-code-execution
to deny
.
# Allow external code execution when updating dependencies from private registries
version: 2
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
updates:
- package-ecosystem: "bundler"
directory: "/rubygems-server"
insecure-external-code-execution: allow
registries: "*"
schedule:
interval: "monthly"
labels
By default, 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. 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: "weekly"
# 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: "weekly"
# Associate pull requests with milestone "4"
milestone: 4
open-pull-requests-limit
By default, Dependabot opens a maximum of five pull requests for version updates. Once there are five open pull requests from Dependabot, Dependabot will not open any new requests until some of those open requests are merged or closed. 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.
# Specify the number of open pull requests allowed
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Disable version updates for npm dependencies
open-pull-requests-limit: 0
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Allow up to 10 open pull requests for pip dependencies
open-pull-requests-limit: 10
pull-request-branch-name.separator
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.
# Specify a different separator for branch names
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
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, Dependabot automatically rebases open pull requests when it detects any changes to the pull request. Use rebase-strategy
to disable this behavior.
Available rebase strategies
auto
to use the default behavior and rebase open pull requests when changes are detected.disabled
to disable automatic rebasing.
When rebase-strategy
is set to auto
, Dependabot attempts to rebase pull requests in the following cases.
- When you use Dependabot version updates, for any open Dependabot pull request when your schedule runs.
- When you reopen a closed Dependabot pull request.
- When you change the value of
target-branch
in the Dependabot configuration file. For more information about this field, see "target-branch
." - When Dependabot detects that a Dependabot pull request is in conflict after a recent push to the target branch.
Note: Dependabot will keep rebasing a pull request indefinitely until the pull request is closed, merged or you disable Dependabot updates.
When rebase-strategy
is set to disabled
, Dependabot stops rebasing pull requests.
Note: This behavior only applies to pull requests that go into conflict with the target branch. Dependabot will keep rebasing pull requests opened prior to the rebase-strategy
setting being changed, and pull requests that are part of a scheduled run.
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.
# Disable automatic rebasing
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Disable rebasing for npm pull requests
rebase-strategy: "disabled"
registries
To allow Dependabot to access a private package registry when performing a version update, you must include a registries
setting within the relevant updates
configuration. You can allow all of the defined registries to be used by setting registries
to "*"
. Alternatively, you can list the registries that the update can use. To do this, use the name of the registry as defined in the top-level registries
section of the dependabot.yml file. For more information, see "Configuration options for private registries" below.
To allow Dependabot to use bundler
, mix
, and pip
package managers to update dependencies in private registries, you can choose to allow external code execution. For more information, see insecure-external-code-execution
above.
# Allow Dependabot to use one of the two defined private registries
# when updating dependency versions for this ecosystem
version: 2
registries:
maven-github:
type: maven-repository
url: https://maven.pkg.github.com/octocat
username: octocat
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
npm-npmjs:
type: npm-registry
url: https://registry.npmjs.org
username: octocat
password: ${{secrets.MY_NPM_PASSWORD}}
updates:
- package-ecosystem: "gitsubmodule"
directory: "/"
registries:
- maven-github
schedule:
interval: "monthly"
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: "weekly"
# Add reviewers
reviewers:
- "octocat"
- "my-username"
- "my-org/python-team"
schedule.day
When you set a weekly
update schedule, by default, Dependabot checks for new versions on Monday at a random set time for the repository. 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, Dependabot checks for new versions at a random set time for the repository. 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: "weekly"
# Check for npm updates at 9am UTC
time: "09:00"
schedule.timezone
By default, Dependabot checks for new versions at a random set time for the repository. 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: "weekly"
time: "09:00"
# Use Japan Standard Time (UTC +09:00)
timezone: "Asia/Tokyo"
target-branch
By default, 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: "weekly"
# 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. Don't use this option if you're using gomod
as Dependabot automatically detects vendoring for this tool.
# 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 manager | Required file path for vendored dependencies | More information |
---|---|---|
bundler | The dependencies must be in the vendor/cache directory. Other file paths are not supported. | bundle cache documentation |
gomod | No path requirement (dependencies are usually located in the vendor directory) | go mod vendor documentation |
versioning-strategy
When 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
Option | Supported by | Action |
---|---|---|
lockfile-only | bundler , cargo , composer , mix , npm , pip | Only create pull requests to update lockfiles. Ignore any new versions that would require package manifest changes. |
auto | bundler , cargo , composer , mix , npm , pip | Follow the default strategy described above. |
widen | composer , npm | Relax the version requirement to include both the new and old version, when possible. |
increase | bundler , composer , npm | Always increase the version requirement to match the new version. |
increase-if-necessary | bundler , composer , npm | Increase the version requirement only when required by the new version. |
# Customize the manifest version strategy
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Update the npm manifest file to relax
# the version requirements
versioning-strategy: widen
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
# Increase the version requirements for Composer
# only when required
versioning-strategy: increase-if-necessary
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Only allow updates to the lockfile for pip and
# ignore any version updates that affect the manifest
versioning-strategy: lockfile-only
Configuration options for private registries
The top-level registries
key is optional. It allows you to specify authentication details that Dependabot can use to access private package registries.
Note: Private registries behind firewalls on private networks are not supported.
The value of the registries
key is an associative array, each element of which consists of a key that identifies a particular registry and a value which is an associative array that specifies the settings required to access that registry. The following dependabot.yml file, configures a registry identified as dockerhub
in the registries
section of the file and then references this in the updates
section of the file.
# Minimal settings to update dependencies in one private registry
version: 2
registries:
dockerhub: # Define access for a private registry
type: docker-registry
url: registry.hub.docker.com
username: octocat
password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
- package-ecosystem: "docker"
directory: "/docker-registry/dockerhub"
registries:
- dockerhub # Allow version updates for dependencies in this registry
schedule:
interval: "monthly"
You use the following options to specify access settings. Registry settings must contain a type
and a url
, and typically either a username
and password
combination or a token
.
Option� � � � � � � � � � � � � � � � | Description |
---|---|
type | Identifies the type of registry. See the full list of types below. |
url | The URL to use to access the dependencies in this registry. The protocol is optional. If not specified, https:// is assumed. Dependabot adds or ignores trailing slashes as required. |
username | The username that Dependabot uses to access the registry. |
password | A reference to a Dependabot secret containing the password for the specified user. For more information, see "Managing encrypted secrets for Dependabot." |
key | A reference to a Dependabot secret containing an access key for this registry. For more information, see "Managing encrypted secrets for Dependabot." |
token | A reference to a Dependabot secret containing an access token for this registry. For more information, see "Managing encrypted secrets for Dependabot." |
replaces-base | For registries with type: python-index , if the boolean value is true , pip resolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple ). |
Each configuration type
requires you to provide particular settings. Some types allow more than one way to connect. The following sections provide details of the settings you should use for each type
.
composer-repository
The composer-repository
type supports username and password.
registries:
composer:
type: composer-repository
url: https://repo.packagist.com/example-company/
username: octocat
password: ${{secrets.MY_PACKAGIST_PASSWORD}}
docker-registry
Dependabot works with any container registries that implement the OCI container registry spec. For more information, see https://github.com/opencontainers/distribution-spec/blob/main/spec.md. Dependabot supports authentication to private registries via a central token service or HTTP Basic Auth. For further details, see Token Authentication Specification in the Docker documentation and Basic access authentication on Wikipedia.
The docker-registry
type supports username and password.
registries:
dockerhub:
type: docker-registry
url: https://registry.hub.docker.com
username: octocat
password: ${{secrets.MY_DOCKERHUB_PASSWORD}}
The docker-registry
type can also be used to pull from private Amazon ECR using static AWS credentials.
registries:
ecr-docker:
type: docker-registry
url: https://1234567890.dkr.ecr.us-east-1.amazonaws.com
username: ${{secrets.ECR_AWS_ACCESS_KEY_ID}}
password: ${{secrets.ECR_AWS_SECRET_ACCESS_KEY}}
git
The git
type supports username and password.
registries:
github-octocat:
type: git
url: https://github.com
username: x-access-token
password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
hex-organization
The hex-organization
type supports organization and key.
registries:
github-hex-org:
type: hex-organization
organization: github
key: ${{secrets.MY_HEX_ORGANIZATION_KEY}}
maven-repository
The maven-repository
type supports username and password.
registries:
maven-artifactory:
type: maven-repository
url: https://artifactory.example.com
username: octocat
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
npm-registry
The npm-registry
type supports username and password, or token.
When using username and password, your .npmrc
's auth token may contain a base64
encoded _password
; however, the password referenced in your Dependabot configuration file must be the original (unencoded) password.
registries:
npm-npmjs:
type: npm-registry
url: https://registry.npmjs.org
username: octocat
password: ${{secrets.MY_NPM_PASSWORD}} # Must be an unencoded password
registries:
npm-github:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
nuget-feed
The nuget-feed
type supports username and password, or token.
registries:
nuget-example:
type: nuget-feed
url: https://nuget.example.com/v3/index.json
username: octocat@example.com
password: ${{secrets.MY_NUGET_PASSWORD}}
registries:
nuget-azure-devops:
type: nuget-feed
url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json
username: octocat@example.com
password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}
python-index
The python-index
type supports username and password, or token.
registries:
python-example:
type: python-index
url: https://example.com/_packaging/my-feed/pypi/example
username: octocat
password: ${{secrets.MY_BASIC_AUTH_PASSWORD}}
replaces-base: true
registries:
python-azure:
type: python-index
url: https://pkgs.dev.azure.com/octocat/_packaging/my-feed/pypi/example
username: octocat@example.com
password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}
replaces-base: true
rubygems-server
The rubygems-server
type supports username and password, or token.
registries:
ruby-example:
type: rubygems-server
url: https://rubygems.example.com
username: octocat@example.com
password: ${{secrets.MY_RUBYGEMS_PASSWORD}}
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
terraform-registry
The terraform-registry
type supports a token.
registries:
terraform-example:
type: terraform-registry
url: https://terraform.example.com
token: ${{secrets.MY_TERRAFORM_API_TOKEN}}