Note: GitHub Dependabot version updates are currently in beta and subject to change. To use the beta feature, follow the instructions in this article.
You enable GitHub Dependabot version updates by checking a configuration file in to your repository. When GitHub detects the dependabot.yml file, it installs the GitHub Dependabot App, if it isn't already installed (for example, if security updates are enabled). The app then raises pull requests to keep the dependencies you configure up-to-date. For each package manager's dependencies that you want to update, you must specify the location of the package manifest files and how often to check for updates to the dependencies listed in those files. For information about enabling security updates, see "Configuring GitHub Dependabot security updates."
When you first enable version updates, you may have many dependencies that are outdated and some may be many versions behind the latest version. GitHub Dependabot checks for outdated dependencies as soon as the app is installed. You may see new pull requests for version updates within minutes of adding the configuration file, depending on the number of manifest files for which you configure updates.
To keep pull requests manageable and easy to review, the app raises a maximum of five pull requests to start bringing dependencies up to the latest version. If you merge some of these first pull requests before the next scheduled update, then further pull requests are opened up to a maximum of five (you can change this limit). For more information, see "Customizing dependency updates."
- Create a dependabot.yml configuration file.
package-ecosystemto specify the package managers to monitor.
- For each package manager, use:
directoryto specify the location of the manifest or other definition files.
schedule.intervalto specify how often to check for new versions.
- Check the dependabot.yml configuration file in to the
.githubdirectory of the repository.
The example dependabot.yml file below configures version updates for two package mangers: npm and Docker. When this file is checked in, GitHub Dependabot checks the manifest files on the default branch for outdated dependencies. If it finds outdated dependencies, it will raise pull requests against the default branch to update the dependencies.
# Basic dependabot.yml file with # minimum configuration for two package managers version: 2 updates: # Enable version updates for npm - package-ecosystem: "npm" # Look for `package.json` and `lock` files in the `root` directory directory: "/" # Check the npm registry for updates every day (weekdays) schedule: interval: "daily" # Enable version updates for Docker - package-ecosystem: "docker" # Look for a `Dockerfile` in the `root` directory directory: "/" # Check for updates once a week schedule: interval: "weekly"
In the example above, if the Docker dependencies were very outdated, you might want to start with a
daily schedule until the dependencies are up-to-date, and then drop back to a weekly schedule.
If you want to enable version updates on forks, there's an extra step. Version updates are not automatically enabled on forks when a dependabot.yml configuration file is present. This ensures that fork owners don't unintentionally enable version updates when they pull changes including a dependabot.yml configuration file from the original repository.
On a fork, you also need to explicitly enable GitHub Dependabot.
- On GitHub, navigate to the main page of the repository.
- Under your repository name, click Insights.
- In the left sidebar, click Dependency graph.
- Under "Dependency graph", click Dependabot.
- Under "Enable Dependabot", click Enable Dependabot.
After you enable version updates, you'll see a new Dependabot tab in the dependency graph for the repository. This tab shows which package managers GitHub Dependabot is configured to monitor and when the app last checked for new versions.
For information, see "Listing dependencies configured for version updates."
You can disable version updates entirely by deleting the dependabot.yml file from your repository. More usually, you want to disable updates temporarily for one or more dependencies, or package managers.
- Package managers: disable by setting
open-pull-requests-limit: 0or by commenting out the relevant
package-ecosystemin the configuration file.
- Specific dependencies: disable by adding
ignoreattributes for packages or applications that you want to exclude from updates.
When you disable dependencies, you can use wild cards to match a set of related libraries. You can also specify which versions to exclude. This is particularly useful if you need to block updates to a library, pending work to support a breaking change to its API, but want to get any security fixes to the version you use.
The example dependabot.yml file below includes examples of the different ways to disable updates to some dependencies, while allowing other updates to continue.
# dependabot.yml file with updates # disabled for Docker and limited for npm version: 2 updates: # Configuration for Dockerfile - package-ecosystem: "docker" directory: "/" schedule: interval: "weekly" # Disable all pull requests for Docker dependencies open-pull-requests-limit: 0 # Configuration for npm - package-ecosystem: "npm" directory: "/" schedule: interval: "daily" # Overwrite any ignores created using `@dependabot ignore` commands ignore: # Ignore updates to packages that start 'aws' # Wildcards match zero or more arbitrary characters - dependency-name: "aws*" # Ignore some updates to the 'express' package - dependency-name: "express" # Ignore only new versions for 4.x and 5.x versions: ["4.x", "5.x"]
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.
For more information about checking for existing ignore preferences, see "Configuration options for dependency updates."