Configuring Dependabot version updates

注意

站点管理员必须先为你的 GitHub Enterprise Server 实例设置 Dependabot updates，然后你才能使用此功能。有关详细信息，请参阅为企业启用 Dependabot.

如果企业所有者在企业级别设置了策略，你可能无法启用或禁用 Dependabot updates。有关详细信息，请参阅“强制实施企业的代码安全性和分析策略”。

About version updates for dependencies

You enable Dependabot version updates by checking a dependabot.yml configuration file in to your repository's .github directory. Dependabot 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 Dependabot security updates.

首次启用版本更新时，您可能有很多过时的依赖项，其中一些可能为许多落后于最新版本的版本。 Dependabot 将在其启用后立即检查过时的依赖项。根据您配置更新的清单文件的数量，您可能会在添加配置文件后几分钟内看到新的版本更新拉取请求。 Dependabot 也会在配置文件后续更改时运行更新。

为使拉取请求保持可管理和易于审查，Dependabot 最多提出五个拉取请求，以便开始将依赖项更新至最新版本。如果您在下次预定的更新之前先合并了这些拉取请求，剩余的拉取请求将在下次更新时打开，最多不超过此限。可以通过设置open-pull-requests-limit配置选项来更改打开的拉取请求的最大数量。

若要进一步减少可能看到的拉取请求数，可以使用 groups 配置选项将依赖项集组合在一起（每个包生态系统）。然后，Dependabot 提出单个拉取请求，以将组中尽可能多的依赖项同时更新到最新版本。 For more information, see 优化 Dependabot 版本更新的拉取请求创建.

有时，由于配置错误或版本不兼容，你可能会看到 Dependabot 运行失败。运行失败 15 次后，Dependabot version updates 将跳过后续的计划运行，直到你手动触发依赖项关系图更新检查。 Dependabot security updates 仍照常运行。

By default only direct dependencies that are explicitly defined in a manifest are kept up to date by Dependabot version updates. You can choose to receive updates for indirect dependencies defined in lock files. For more information, see Controlling which dependencies are updated by Dependabot.

在运行安全性或版本更新时，有些生态系统必须能够解决来自其来源的所有依赖项，以验证版本更新是否成功。如果清单或锁定文件包含任何私有依赖项，Dependabot 必须能够访问这些依赖项所在的位置。组织所有者可以授予 Dependabot 访问包含同一个组织内项目依赖项的私有仓库. 有关详细信息，请参阅“管理组织的安全和分析设置”。你可以在存储库的 dependabot.yml 配置文件中配置对专用注册表的访问。有关详细信息，请参阅“Configuring access to private registries for Dependabot”。 Additionally, Dependabot doesn't support private GitHub dependencies for all package managers. For more information, see Dependabot 支持的生态系统和存储库 and GitHub 语言支持.

Enabling Dependabot version updates

You enable Dependabot version updates by committing a dependabot.yml configuration file to your repository.

Create a dependabot.yml configuration file in the .github directory of your repository. You can use the snippet below as a starting point. For information about the options you can use to customize how Dependabot maintains your repositories, see Dependabot 选项参考.

YAML

# To get started with Dependabot version updates, you'll need to specify which
# package ecosystems to update and where the package manifests are located.

version: 2
updates:
- package-ecosystem: "" # See documentation for possible values
  directory: "/" # Location of package manifests
  schedule:
    interval: "weekly"

# To get started with Dependabot version updates, you'll need to specify which
# package ecosystems to update and where the package manifests are located.

version: 2
updates:
- package-ecosystem: "" # See documentation for possible values
  directory: "/" # Location of package manifests
  schedule:
    interval: "weekly"

Add a version. This key is mandatory. The file must start with version: 2.
Optionally, if you have dependencies in a private registry, add a registries section containing authentication details. For more information, see Configuring access to private registries for Dependabot.
Add an updates section, with an entry for each package manager you want Dependabot to monitor. This 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. For more information, see About the dependabot.yml file in "Dependabot options reference."
For each package manager, use:
- package-ecosystem to specify the package manager. For more information about the supported package managers, see package-ecosystem.
- directories or directory to specify the location of multiple manifest or other definition files. For more information, see Defining multiple locations for manifest files.
- schedule.interval to specify how often to check for new versions.
将 dependabot.yml 配置文件签入存储库的 .github 目录中。

Example `dependabot.yml` file

The example dependabot.yml file below configures version updates for three package managers: npm, Docker, and GitHub Actions. When this file is checked in, 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.

YAML

# Basic `dependabot.yml` file with
# minimum configuration for three 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"

  # Enable version updates for GitHub Actions
  - package-ecosystem: "github-actions"
    # Workflow files stored in the default location of `.github/workflows`
    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
    directory: "/"
    schedule:
      interval: "weekly"

# Basic `dependabot.yml` file with
# minimum configuration for three 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"

  # Enable version updates for GitHub Actions
  - package-ecosystem: "github-actions"
    # Workflow files stored in the default location of `.github/workflows`
    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
    directory: "/"
    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.

Enabling version updates on forks

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 Dependabot.

在 GitHub 上，导航到存储库的主页面。
在仓库名称下，单击 “Settings”****。如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。
在边栏的“Security”部分中，单击“ Code security”****。
Under "Code security," to the right of "Dependabot version updates," click Enable to allow Dependabot to initiate version updates.

Checking the status of version updates

After you enable version updates, the Dependabot tab in the dependency graph for the repository is populated. This tab shows which package managers Dependabot is configured to monitor and when Dependabot last checked for new versions.

Screenshot of the Dependency graph page. A tab, titled "Dependabot," is highlighted with an orange outline.

For information, see Listing dependencies configured for version updates.

Disabling Dependabot 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: 0 or by commenting out the relevant package-ecosystem in the configuration file.
Specific dependencies: disable by adding ignore attributes 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.

Example disabling version updates for some dependencies

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: "weekly"
    ignore:
      # Ignore updates to packages that start with '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"]
      # For all packages, ignore all patch updates
      - dependency-name: "*"
        update-types: ["version-update:semver-patch"]

For more information about checking for existing ignore preferences, see Dependabot 选项参考.

谁可以使用此功能？

本文内容