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

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

谁可以使用此功能？

具有写入访问权限的用户

在本文中

关于专用注册表

Dependabot version updates 使依赖项保持最新，并且 Dependabot security updates 更新易受攻击的依赖项。 Dependabot 可以访问公共注册表。 此外，还可以授予 Dependabot 对专用包注册表和专用 GitHub 存储库的访问权限，以便可以将专用和内部资源依赖项与公共依赖项一样进行更新和保护。

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

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

要允许 Dependabot 访问托管在专用或限制在内部网络中的注册表，请配置 Dependabot 在 GitHub Actions 自托管运行器上运行。 有关详细信息，请参阅 在自托管运行器上配置 Dependabot。

配置专用注册表

可以在组织级别配置 Dependabot对专用注册表的访问。

组织级别的注册表支持 令牌、 用户名和密码以及 OIDC 身份验证。

有关配置的详细信息，请参阅 授予安全功能访问专用注册表的权限。

还可以在 Dependabot 文件中配置 dependabot.yml 对专用注册表的访问。 顶级的 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 机密还包括由 GitHub Actions 拉取请求触发的 Dependabot 工作流使用的机密。 Dependabot 本身可能不使用这些机密，但工作流需要这些机密。 有关详细信息，请参阅“对 GitHub Actions 上的 Dependabot 进行故障排除”。

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

YAML
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}

命名您的密码

Dependabot 机密的名称：

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

为 Dependabot 添加存储库密钥

要为个人帐户存储库创建机密，你必须是存储库所有者。 要为组织存储库创建密码，必须具有 admin 访问权限。

  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 允许列表，你可以在 meta API 终结点中的 actions 键下找到 Dependabot 用于访问注册表的 IP 地址。 有关详细信息，请参阅 元数据的 REST API 端点 和 关于 GitHub Actions 运行程序上的 Dependabot。

使用 OIDC 进行身份验证

Dependabot 可以使用 OpenID Connect （OIDC） 通过专用注册表进行身份验证，而无需将长期凭据存储为存储库机密。

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

提示

OIDC 身份验证也适用于 组织级 专用注册表，可以通过组织设置 UI 或 REST API 进行配置。 有关详细信息，请参阅“授予安全功能访问专用注册表的权限”。

Dependabot 当注册表托管在以下提供程序之一上时，支持对使用 username 和 password 身份验证的任何注册表类型进行 OIDC 身份验证：

  • AWS CodeArtifact
  • Azure DevOps工件
  • Cloudsmith
  • Google Cloud Artifact Registry
  • 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 }}

Cloudsmith

Cloudsmith 需要值 namespace， service-slug以及 audience。 该 api-host 字段是可选的，默认为 api.cloudsmith.io：

registries:
  my-cloudsmith-feed:
    type: npm-registry
    url: https://dl.cloudsmith.io/MY-NAMESPACE/MY-REPOSITORY/npm/
    namespace: MY-NAMESPACE
    service-slug: MY-SERVICE-SLUG
    audience: https://github.com/GITHUB-ORG
    api-host: api.cloudsmith.io  # if required by your feed

Google Cloud Artifact Registry

Google Cloud Artifact Registry 需要值 url 和 workload-identity-provider。 值 service-account 和 audience 可选：

registries:
  my-gcp-artifact-registry:
    type: docker-registry
    url: https://REGION-docker.pkg.dev
    workload-identity-provider: projects/PROJECT-NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
    service-account: SA-NAME@PROJECT-ID.iam.gserviceaccount.com  # if required by your provider
    audience: MY-AUDIENCE  # if required by your provider

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