为 Dependabot 配置对专用注册表的访问权限

可以将 Dependabot 配置为访问专用注册表中存储的依赖项。 可将身份验证信息（如密码和访问令牌）存储为加密机密，然后在 Dependabot 配置文件中引用这些信息。如果在专用网络上有注册表，则还可以在自托管运行器上运行 Dependabot 时配置 Dependabot 访问权限。

谁可以使用此功能？

具有写入访问权限的用户

在本文中

关于专用注册表

Dependabot version updates 可保持依赖项最新，Dependabot security updates 可更新存在漏洞的依赖项。 Dependabot 可以访问公共注册表。 此外，你可以为 Dependabot 授权访问私有包注册表和私有 GitHub 存储库，以确保私有和内部源依赖项与公共依赖项一样保持最新和安全。

在大多数生态系统中，专用依赖项通常会发布到专用包注册表。 这些专用注册表与公共注册表类似，但需要身份验证。

对于特定生态系统，你可以配置 Dependabot _仅_访问私有注册表，方法是移除对公共注册表的调用。 有关详细信息，请参阅“删除对公共注册表的 Dependabot 访问权限”。

要允许 Dependabot 访问私有托管或仅限于内部网络的注册表，请将 Dependabot 配置为在 GitHub Actions 自托管运行器上运行。 有关详细信息，请参阅“在自托管运行器上配置 Dependabot”。

配置专用注册表

你可以在组织级别配置 Dependabot 对专用注册表的访问。 有关如何配置该设置的详细信息，请参阅 授予安全功能访问专用注册表的权限。

你还可以在 dependabot.yml 文件中配置 Dependabot 对专用注册表的访问。 顶级的 registries 密钥是可选的，用于指定身份验证详细信息。

dependabot.yml 文件中有 2 个位置可以使用 registries 密钥：

  • 在顶级，可在这里定义注册表及其访问信息（如果需要）。
  • 在 updates 块中，可以使用 registries: "*" 告知 Dependabot 使用你在顶级定义的任何或所有注册表。
# registries: gradle-artifactory - provides access details for the gradle-artifactory registry
# registries: "*" - allows Dependabot to use all the defined registries specified at the top level

version: 2
registries:
  gradle-artifactory:
    type: maven-repository
    url: https://acme.jfrog.io/artifactory/my-gradle-registry
    username: octocat
    password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
updates:
  - package-ecosystem: "gradle"
    directory: "/"
    registries: "*"
    schedule:
      interval: "monthly"

您使用以下选项来指定访问设置。 注册表设置必须包含 type 和 url，并且通常包含 username 和 password 组合或 token。

参数用途
REGISTRY_NAME必需： 定义注册表的标识符。
type必需： 确定注册表的类型。
身份验证详细信息必需： 提供身份验证详细信息所支持的参数因不同类型的注册表而异。
url必需： 用于访问此注册表中的依赖项的 URL。 协议是可选的。 如果未指定，则假定为 https://。 Dependabot 根据需要添加或忽略尾随斜线。
replaces-base如果布尔值为 true，Dependabot 会使用指定的 url 而不是该生态系统的基 URL 来解析依赖项。

有关可用配置选项及支持类型的更多信息，请参阅 Dependabot 选项参考。

存储供 Dependabot 使用的凭据

若要授予 Dependabot 对 GitHub 支持的专用注册表的访问权限，可以将注册表的访问令牌或机密存储在存储库或组织的机密存储中。

关于 Dependabot 的加密机密

Dependabot 密码是您在组织级别或仓库级别创建的加密凭据。 当您在组织级别添加密码时，可以指定哪些仓库可以访问该密码。 您可以使用密码允许 Dependabot 更新位于私人包注册表中的依赖项。 添加机密时，它会在到达 GitHub 之前进行加密，并且保持加密状态，直到 Dependabot 将其用于访问专用包注册表。

Dependabot 机密还包括 Dependabot 拉取请求触发的 GitHub Actions 工作流所使用的机密。 Dependabot 本身可能不会使用这些机密，但工作流需要这些机密。 有关详细信息，请参阅“对 GitHub Actions 上的 Dependabot 进行故障排除”。

添加 Dependabot 机密后，可在 dependabot.yml 配置文件中引用它，如下所示：${{secrets.NAME}}，其中“NAME”是为机密选择的名称。 例如：

YAML
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}

命名您的密码

Dependabot 密码的名称：

  • 只能包含字母数字字符（[A-Z]、[0-9]）或下划线 (_)。 不允许空格。 如果您输入小写字母，这些字母将更改为大写字母。
  • 不得以 GITHUB_ 前缀开头。
  • 不能以数字开头。

为 Dependabot 添加仓库密码

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

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

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Security”部分中，选择“ Secrets and variables”，然后单击“Dependabot”********。

  4. 单击新建存储库密钥。

  5. 在名称输入框中为你的密钥输入一个名称。

  6. 输入密码的值。

  7. 单击添加密钥。

    密码名称列在 Dependabot 密码页面上。 你可以单击更新来更改密钥值。 你可以单击删除来删除密钥。

将组织机密添加到 Dependabot

在组织中创建密码时，可以使用策略来限制可以访问该密码的仓库。 例如，您可以将访问权限授予所有仓库，也可以限制仅私有仓库或指定的仓库列表拥有访问权限。

要在组织级别创建机密，必须具有 admin 访问权限。

  1. 在 GitHub 上，导航到组织的主页面。

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

    组织配置文件中选项卡的屏幕截图。 “设置”选项卡以深橙色标出。

  3. 在边栏的“Security”部分中，选择“ Secrets and variables”，然后单击“Dependabot”********。 忽略“私有注册表”选项，此选项仅用于 code scanning 的默认设置。

  4. 单击新建组织密钥。

  5. 在名称输入框中为你的密钥输入一个名称。

  6. 输入密码的值。

  7. 从“存储库访问”下拉列表中，选择访问策略。

  8. 如果选择了选定存储库：

    • 单击“”。
    • 在对话框中，选择可以访问此机密的存储库。
    • 单击更新选择。

  9. 单击添加密钥。

    机密的名称列在 Dependabot 机密页面中。 你可以单击更新来更改密钥值或其访问策略。 你可以单击删除来删除密钥。

配置防火墙 IP 规则

可将 Dependabot 相关的 IP 地址添加到注册表 IP 允许列表中。

如果专用注册表配置了 IP 允许列表，则可在 actions 键下找到用于访问元 API 终结点中的注册表的 IP 地址 Dependabot。 有关详细信息，请参阅 元数据的 REST API 端点 和 关于 GitHub Actions 运行程序上的 Dependabot。

使用 OIDC 进行身份验证

Dependabot 可以使用 OpenID Connect (OIDC) 向专用注册表进行身份验证，而无需将长期存在的凭据存储为存储库密钥。

使用基于 OIDC 的身份验证，Dependabot 更新作业可以从你的云标识提供者那里动态获取短期凭据，就像使用 OIDC 联合身份验证的 GitHub Actions 工作流一样。

当注册表托管在以下一个云提供商中时，Dependabot 支持对使用 username 和 password 身份验证的任何类型的注册表进行 OIDC 身份验证。

  • AWS CodeArtifact
  • Azure DevOps 工件
  • JFrog Artifactory

若要配置 OIDC 身份验证，需要在注册表配置中指定不同的值来替代username和password。

AWS CodeArtifact

AWS CodeArtifact 需要值aws-region、account-id、role-name和domain``domain-owner。 audience 字段为可选。

registries:
  my-aws-codeartifact-feed:
    type: npm-registry
    url: https://MY_DOMAIN-MY-ACCOUNT_ID.d.codeartifact.REGION.amazonaws.com/npm/MY_REPOSITORY/
    aws-region: REGION
    account-id: '123456789012'
    role-name: MY_ROLE_NAME
    domain: MY_DOMAIN
    domain-owner: '987654321098'
    audience: MY_AUDIENCE  # if required by your feed

Azure DevOps 工件

Azure DevOps Artifacts 需要值 tenant-id 和 client-id：

registries:
  my-azure-devops-artifacts-feed:
    type: npm-registry
    url: https://pkgs.dev.azure.com/MY-ORGANIZATION/MY-PROJECT/_packaging/MY-FEED/npm/registry/
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    client-id: ${{ secrets.AZURE_CLIENT_ID }}

JFrog Artifactory

JFrog Artifactory 需要值 url 和 jfrog-oidc-provider-name。 值 audience 和 identity-mapping-name 可选：

registries:
  my-jfrog-artifactory-feed:
    type: npm-registry
    url: https://JFROG-PLATFORM-URL/artifactory/api/npm/MY-REPOSITORY
    jfrog-oidc-provider-name: MY-PROVIDER
    audience: MY-AUDIENCE  # if required by your feed
    identity-mapping-name: MY-IDENTITY-MAPPING  # if required by your feed

有关 OIDC 工作原理的详细信息，请参阅 OpenID Connect。

允许外部代码执行

当你授予 Dependabot 访问一个或多个注册表的权限时，外部代码执行会自动禁用，以保护你的代码免受受损包的影响。 不过，某些版本更新可能会失败。

如果你需要允许 Dependabot 访问私有包注册表并启用有限的外部代码执行，可以将 insecure-external-code-execution 设置为 allow。 允许 Dependabot 在更新过程中执行清单中的外部代码，其风险并不像听起来那么大：

  • 任何外部代码执行仅能访问与所包含的 updates 设置关联的注册表中的包管理器。
  • 不允许访问顶级 registries 配置中定义的任何注册表。

工具链（如 bundler、mix、pip 及 swift）通常默认允许执行外部代码。

在此示例中，配置文件允许 Dependabot 访问 ruby-github 专用包注册表。 在相同 updates 设置中，insecure-external-code-execution 设置为 allow，这意味着通过依赖项执行的代码将只能访问 ruby-github 注册表，而不能访问 dockerhub 注册表。

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

支持的专用注册表

有关如何配置对 Dependabot 支持的专用注册表的访问权限的示例。

cargo-registry

          `cargo-registry` 类型支持令牌。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

registries:
  cargo-example:
    type: cargo-registry
    registry: "name-of-your-registry"
    url: https://cargo.cloudsmith.io/foobaruser/test/
    token: "Token ${{secrets.CARGO_TOKEN}}"

我们已针对 https://cargo.cloudsmith.io 专用注册表测试此配置。

composer-repository

          `composer-repository` 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  composer:
    type: composer-repository
    url: https://repo.packagist.com/example-company/
    username: octocat
    password: ${{secrets.MY_PACKAGIST_PASSWORD}}

docker-registry

Dependabot 可与实现 OCI 容器注册表规范的任何容器注册表配合使用。有关详细信息，请参阅 https://github.com/opencontainers/distribution-spec/blob/main/spec.md。 Dependabot 支持通过中央令牌服务或 HTTP 基本身份验证对专用注册表进行身份验证。有关更多详细信息，请参阅 Docker 文档中的令牌身份验证规范和维基百科上的基本访问身份验证。

          `docker-registry` 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  dockerhub:
    type: docker-registry
    url: https://registry.hub.docker.com
    username: octocat
    password: ${{secrets.MY_DOCKERHUB_PASSWORD}}
    replaces-base: true

          `docker-registry` 类型还可用于通过静态 AWS 凭据从专用 Amazon ECR 中拉取。
YAML
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}}
    replaces-base: true

git

          `git` 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。
YAML
registries:
  github-octocat:
    type: git
    url: https://github.com
    username: x-access-token
    password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}

goproxy-server

          `goproxy-server` 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  my-private-registry:
    type: goproxy-server
    url: https://acme.jfrog.io/artifactory/api/go/my-repo
    username: octocat
    password: ${{secrets.MY_GO_REGISTRY_TOKEN}}

helm-registry

该 helm-registry 类型仅支持 HTTP 基本身份验证，不支持符合 OCI 的注册表。 如果你需要访问符合 OCI 规范的 Helm 图表注册表，请改为配置 docker-registry。

          `helm-registry` 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  helm_registry:
    type: helm-registry
    url: https://registry.example.com
    username: octocat
    password: ${{secrets.MY_REGISTRY_PASSWORD}}

hex-organization

          `hex-organization` 类型支持组织和密钥。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  github-hex-org:
    type: hex-organization
    organization: github
    key: ${{secrets.MY_HEX_ORGANIZATION_KEY}}

hex-repository

          `hex-repository` 类型支持身份验证密钥。

          `repo` 是必填字段，必须与依赖声明中使用的存储库名称匹配。

          `public-key-fingerprint` 为可选配置字段，表示 Hex 存储库的公钥指纹。 
          `public-key-fingerprint` 由 Hex 使用以与私有存储库建立信任。 
          `public-key-fingerprint` 字段可以以纯文本形式列出，也可以存储为 Dependabot 机密。
YAML
registries:
   github-hex-repository:
     type: hex-repository
     repo: private-repo
     url: https://private-repo.example.com
     auth-key: ${{secrets.MY_AUTH_KEY}}
     public-key-fingerprint: ${{secrets.MY_PUBLIC_KEY_FINGERPRINT}}

maven-repository

该 maven-repository 类型支持用户名、密码和 replaces-base。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  maven-artifactory:
    type: maven-repository
    url: https://acme.jfrog.io/artifactory/my-maven-registry
    username: octocat
    password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
    replaces-base: true

还可以使用 OIDC 身份验证访问 JFrog Artifactory。 通过 OIDC，Dependabot 可以动态获取短期凭证，而不是使用静态凭证。

YAML
registries:
  maven-artifactory-oidc:
    type: maven-repository
    url: https://acme.jfrog.io/artifactory/my-maven-registry
    tenant-id: ${{secrets.ARTIFACTORY_TENANT_ID}}
    client-id: ${{secrets.ARTIFACTORY_CLIENT_ID}}
    replaces-base: true

npm-registry

          `npm-registry` 类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

使用用户名和密码时，.npmrc 的身份验证令牌可能包含 base64 编码的 _password；但是，Dependabot 配置文件中引用的密码必须是原始（未编码）密码。

注意

使用 npm.pkg.github.com 时，请不要包含路径。 请改用没有路径的 https://npm.pkg.github.com URL。

YAML
registries:
  npm-npmjs:
    type: npm-registry
    url: https://registry.npmjs.org
    username: octocat
    password: ${{secrets.MY_NPM_PASSWORD}}  # Must be an unencoded password
    replaces-base: true
YAML
registries:
  npm-github:
    type: npm-registry
    url: https://npm.pkg.github.com
    token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
    replaces-base: true

出于安全原因， Dependabot 不设置环境变量。 Yarn（v2 及更高版本）要求设置任何访问的环境变量。 访问 .yarnrc.yml 文件中的环境变量时，应提供回退值，例如 ${ENV_VAR-fallback} 或 ${ENV_VAR:-fallback}。 有关详细信息，请参阅 Yarn 文档中的 Yarnrc 文件。

nuget-feed

          `nuget-feed` 类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

          `nuget-feed` 不支持 `replaces-base` 参数。
YAML
registries:
  nuget-example:
    type: nuget-feed
    url: https://nuget.example.com/v3/index.json
    username: octocat@example.com
    password: ${{secrets.MY_NUGET_PASSWORD}}
YAML
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}}

还可以使用 OIDC 身份验证访问 Azure DevOps Artifacts。 通过 OIDC，Dependabot 可以动态获取短期凭证，而不是使用静态凭证。

YAML
registries:
  nuget-azure-devops-oidc:
    type: nuget-feed
    url: https://pkgs.dev.azure.com/MyOrganization/MyProject/_packaging/MyArtifactFeedName/nuget/v3/index.json
    tenant-id: ${{secrets.AZURE_TENANT_ID}}
    client-id: ${{secrets.AZURE_CLIENT_ID}}

可以从 Entra ID 应用注册的概述页获取这些 AZURE_TENANT_ID 值和 AZURE_CLIENT_ID 值。

pub-repository

          `pub-repository` 类型支持 URL 和令牌。
YAML
registries:
  my-pub-registry:
    type: pub-repository
    url: https://example-private-pub-repo.dev/optional-path
    token: ${{secrets.MY_PUB_TOKEN}}
updates:
  - package-ecosystem: "pub"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - my-pub-registry

python-index

          `python-index` 类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
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
YAML
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

还可以使用 OIDC 身份验证访问 Azure DevOps Artifacts。 通过 OIDC，Dependabot 可以动态获取短期凭证，而不是使用静态凭证。

YAML
registries:
  python-azure-oidc:
    type: python-index
    url: https://pkgs.dev.azure.com/octocat/_packaging/my-feed/pypi/example
    tenant-id: ${{secrets.AZURE_TENANT_ID}}
    client-id: ${{secrets.AZURE_CLIENT_ID}}
    replaces-base: true

rubygems-server

          `rubygems-server` 类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

此注册表类型会与 url 选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据，用于访问不同的路径。 不过，如果同一主机上没有多个注册表，建议省略 url 中的路径，以便注册表的所有路径都会收到凭据。

YAML
registries:
  ruby-example:
    type: rubygems-server
    url: https://rubygems.example.com
    username: octocat@example.com
    password: ${{secrets.MY_RUBYGEMS_PASSWORD}}
    replaces-base: true
YAML
registries:
  ruby-github:
    type: rubygems-server
    url: https://rubygems.pkg.github.com/octocat/github_api
    token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
    replaces-base: true

terraform-registry

          `terraform-registry` 类型支持令牌。
YAML
registries:
  terraform-example:
    type: terraform-registry
    url: https://terraform.example.com
    token: ${{secrets.MY_TERRAFORM_API_TOKEN}}