配置 Dependabot 版本更新

关于依赖项的版本更新

通过将 dependabot.yml 配置文件签入存储库的 .github 目录，可启用 Dependabot version updates。 Dependabot 然后提出拉取请求，使您配置的依赖项保持最新。 对于您想更新的每个包管理器的依赖项，必须指定包清单文件的位置及为文件所列的依赖项检查更新的频率。 有关启用安全更新的信息，请参阅 配置 Dependabot 安全更新。

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

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

若要进一步减少可能看到的拉取请求数，可以使用 groups 配置选项将依赖项集组合在一起（每个包生态系统）。 然后，Dependabot 提出单个拉取请求，以将组中尽可能多的依赖项同时更新到最新版本。有关详细信息，请参阅 使用 Dependabot 版本更新自动更新依赖项。

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

默认情况下，只有清单中显式定义的直接依赖项才会由 Dependabot version updates 保持最新。 可以选择接收锁文件中定义的间接依赖项更新。 有关详细信息，请参阅“Dependabot options reference”。

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

启用 Dependabot version updates

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

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

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

   

3. 在边栏的“Security”部分中，单击“Code security”****。

4. 在“Code security”下“Dependabot version updates”的右侧，单击“Enable”以打开仓库 .github 目录中的基本 dependabot.yml 配置文件****。 For information about the options you can use to customize how Dependabot maintains your repositories, see Dependabot options reference.

   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 部分。 有关详细信息，请参阅“dependabot.yml 文件配置选项”中的 registries。

7. 添加 updates 部分，并输入希望 Dependabot 监视的每个包管理器的条目。 此密钥是必填项。 您使用它来配置 Dependabot 如何更新版本或项目的依赖项。 每个条目都为特定的包管理器配置更新设置。

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

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

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. 在边栏的“Security”部分中，单击“Code security”****。

4. 在“Code security”下“Dependabot version updates”的右侧，单击“Enable”以允许 Dependabot 启动版本更新****。

检查版本更新的状态

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

如需相关信息，请参阅 Listing dependencies configured for version updates。

禁用 Dependabot version updates

可通过从存储库中删除 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 options reference。