配置 Dependabot 版本更新

关于依赖项的版本更新

您可以通过将dependabot.yml配置文件检入到您的代码库的.github目录中来启用 Dependabot 版本更新。然后，Dependabot 将发出拉取请求以保持您配置的依赖项最新。对于要更新的每个包管理器的依赖项，您必须指定包清单文件的位置以及检查这些文件中列出的依赖项更新的频率。有关启用安全更新的信息，请参阅“配置 Dependabot 安全更新”。

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

为保持拉取请求的可管理性和易于审查，Dependabot 最多会发起五个拉取请求，以开始将依赖项更新到最新版本。如果您在下次计划更新之前合并了其中一些初始拉取请求，则剩余的拉取请求将在下次更新时打开，最多达到该上限。您可以通过设置open-pull-requests-limit 配置选项来更改打开的拉取请求的最大数量。

为了进一步减少您可能看到的拉取请求数量，您可以使用groups 配置选项将依赖项集组合在一起（每个软件包生态系统）。然后，Dependabot 将发起单个拉取请求，以同时将组中尽可能多的依赖项更新到最新版本。更多信息，请参见“自定义依赖项更新”。

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

默认情况下，Dependabot 版本更新仅保持在清单中明确定义的直接依赖项保持最新。您可以选择接收锁定文件中定义的间接依赖项的更新。更多信息，请参见“dependabot.yml 文件的配置选项”。

运行安全或版本更新时，某些生态系统必须能够从其源解析所有依赖项，以验证更新是否成功。如果您的清单或锁定文件包含任何私有依赖项，Dependabot 必须能够访问托管这些依赖项的位置。组织所有者可以授予 Dependabot 访问同一组织内项目私有存储库中包含的依赖项的权限。更多信息，请参见“管理组织的安全和分析设置”。您可以在存储库的 dependabot.yml 配置文件中配置对私有注册表的访问。更多信息，请参见“dependabot.yml 文件的配置选项”。此外，Dependabot 不支持所有包管理器的私有 GitHub 依赖项。更多信息，请参见“Dependabot 支持的生态系统和存储库”和“GitHub 语言支持”。

启用 Dependabot 版本更新

您可以通过将 dependabot.yml 配置文件提交到您的存储库来启用 Dependabot 版本更新。如果您在设置页面中启用此功能，GitHub 将创建一个您可以编辑的基本文件，否则您可以使用任何文件编辑器创建该文件。

1. 在 GitHub 上，导航到存储库的主页。

2. 在您的存储库名称下，单击 设置。如果您看不到“设置”选项卡，请选择下拉菜单，然后单击设置。

   

3. 在侧边栏的“安全”部分中，单击 代码安全和分析。

4. 在“代码安全和分析”下，“Dependabot 版本更新”的右侧，单击启用以在存储库的 .github 目录中打开一个基本的 dependabot.yml 配置文件。有关您可以用来自定义 Dependabot 如何维护存储库的选项的信息，请参见“dependabot.yml 文件的配置选项”。

   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"
   

5. 添加一个 version。此键是必需的。文件必须以 version: 2 开头。

6. 如果您的私有注册表中有依赖项，则可以选择添加包含身份验证详细信息的 registries 部分。更多信息，请参见“registries”（位于“dependabot.yml 文件的配置选项”中）。

7. 添加一个 updates 部分，其中包含您希望 Dependabot 监控的每个包管理器的条目。此键是必需的。您可以使用它来配置 Dependabot 如何更新项目依赖项的版本。每个条目都配置特定包管理器的更新设置。

8. 对于每个包管理器，使用

   • package-ecosystem 指定包管理器。有关受支持的包管理器的更多信息，请参见“package-ecosystem”（位于“dependabot.yml 文件的配置选项”中）。
   • directory 指定清单或其他定义文件的位置。更多信息，请参见“directory”（位于“dependabot.yml 文件的配置选项”中）。
   • directories 指定多个清单或其他定义文件的位置。更多信息，请参见“directories”（位于“dependabot.yml 文件的配置选项”中）。
   • schedule.interval 指定检查新版本的频率。更多信息，请参见“schedule.interval”（位于“dependabot.yml 文件的配置选项”中）。

9. 将 dependabot.yml 配置文件检入存储库的 .github 目录中。

dependabot.yml 文件示例

下面的 dependabot.yml 文件示例配置了两个包管理器的版本更新：npm 和 Docker。检入此文件后，Dependabot 将检查默认分支上的清单文件中的过时依赖项。如果它发现过时的依赖项，它将针对默认分支发出拉取请求以更新这些依赖项。

# 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"

在上面的示例中，如果 Docker 依赖项非常过时，您可能希望从 daily 计划开始，直到依赖项更新为止，然后恢复到每周计划。

在分支上启用版本更新

如果您想在分支上启用版本更新，则需要一个额外的步骤。当存在 dependabot.yml 配置文件时，版本更新不会自动在分支上启用。这确保了分支所有者在从原始存储库拉取包含 dependabot.yml 配置文件的更改时不会无意中启用版本更新。

在分支上，您还需要显式启用 Dependabot。

1. 在 GitHub 上，导航到存储库的主页。

2. 在您的存储库名称下，单击 设置。如果您看不到“设置”选项卡，请选择下拉菜单，然后单击设置。

   

3. 在侧边栏的“安全”部分中，单击 代码安全和分析。

4. 在“代码安全和分析”下，“Dependabot 版本更新”的右侧，单击启用以允许 Dependabot 启动版本更新。

检查版本更新的状态

启用版本更新后，存储库的依赖关系图中的Dependabot选项卡将填充。此选项卡显示 Dependabot 配置为监控哪些包管理器以及 Dependabot 上次检查新版本的时间。

更多信息，请参见“列出配置为进行版本更新的依赖项”。

禁用 Dependabot 版本更新

您可以通过从存储库中删除 dependabot.yml 文件来完全禁用版本更新。更常见的情况是，您希望暂时为一个或多个依赖项或包管理器禁用更新。

• 包管理器：通过设置 open-pull-requests-limit: 0 或注释掉配置文件中的相关 package-ecosystem 来禁用。
• 特定依赖项：通过为要从更新中排除的包或应用程序添加 ignore 属性来禁用。

禁用依赖项时，您可以使用通配符来匹配一组相关的库。您还可以指定要排除的版本。如果您需要阻止对库的更新（待处理的工作以支持对其 API 的重大更改），但希望获得对您使用的版本的任何安全修复，这将特别有用。

禁用某些依赖项的版本更新示例

下面的 dependabot.yml 文件示例包含了禁用某些依赖项更新的不同方法的示例，同时允许其他更新继续进行。

# `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"]

有关检查现有忽略首选项的更多信息，请参见“dependabot.yml 文件的配置选项”。