Configuring access to private registries for Dependabot

You can configure Dependabot to access dependencies stored in private registries. You can store authentication information, like passwords and access tokens, as encrypted secrets and then reference these in the Dependabot configuration file.

谁可以使用此功能？

具有写入访问权限的用户

本文内容

About private registries

Dependabot version updates keeps your dependencies up-to-date and Dependabot security updates updates vulnerable dependencies. Dependabot can access public registries. In addition, you can give Dependabot access to private package registries and private GitHub repositories so that you can keep your private and innersource dependencies as up-to-date and secure as your public dependencies.

In most ecosystems, private dependencies are usually published to private package registries. These private registries are similar to their public equivalents, but they require authentication.

For specific ecosystems, you can configure Dependabot to access only private registries by removing calls to public registries. For more information, see Removing Dependabot access to public registries.

Configuring private registries

You can also configure Dependabot's access to private registries in the dependabot.yml file. The top-level registries key is optional and specifies authentication details.

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 来解析依赖项。

For more information about the configuration options that are available and about the supported types, see Dependabot 选项参考.

Storing credentials for Dependabot to use

To give Dependabot access to the private registries supported by GitHub, you store the registry’s access token or secret in the secret store for your repository or organization.

About encrypted secrets for Dependabot

Dependabot secrets are encrypted credentials that you create at either the organization level or the repository level. When you add a secret at the organization level, you can specify which repositories can access the secret. You can use secrets to allow Dependabot to update dependencies located in private package registries. When you add a secret, it's encrypted before it reaches GitHub and it remains encrypted until it's used by Dependabot to access a private package registry.

Dependabot secrets also include secrets that are used by GitHub Actions workflows triggered by Dependabot pull requests. Dependabot itself may not use these secrets, but the workflows require them. For more information, see 对 GitHub Actions 上的 Dependabot 进行故障排除.

After you add a Dependabot secret, you can reference it in the dependabot.yml configuration file like this: ${{secrets.NAME}}, where "NAME" is the name you chose for the secret. For example:

YAML
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}

Naming your secrets

The name of a Dependabot secret:

  • Can only contain alphanumeric characters ([A-Z], [0-9]) or underscores (_). Spaces are not allowed. If you enter lowercase letters these are changed to uppercase.
  • Must not start with the GITHUB_ prefix.
  • Must not start with a number.

Adding a repository secret for Dependabot

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

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

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

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

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

  4. Click New repository secret.

  5. Type a name for your secret in the Name input box.

  6. Enter the value for your secret.

  7. Click Add secret.

    The name of the secret is listed on the Dependabot secrets page. You can click Update to change the secret value. You can click Remove to delete the secret.

Adding an organization secret for Dependabot

When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.

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

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

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

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

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

  4. Click New organization secret.

  5. Type a name for your secret in the Name input box.

  6. Enter the Value for your secret.

  7. From the Repository access dropdown list, choose an access policy.

  8. If you chose Selected repositories:

    • Click .
    • In the dialog box, select the repositories that can access this secret.
    • Click Update selection.

  9. Click Add secret.

    The name of the secret is listed on the Dependabot secrets page. You can click Update to change the secret value or its access policy. You can click Remove to delete the secret.

Allowing external code execution

When you give Dependabot access to one or more registries, external code execution is automatically disabled to protect your code from compromised packages. However, some version updates may fail.

If you need to allow Dependabot to access a private package registry and enable limited external code execution, you can set insecure-external-code-execution to allow. Allowing Dependabot to execute external code in the manifest during updates is not as scary as it sounds:

  • Any external code execution will only have access to the package managers in the registries associated with the enclosing updates setting.
  • There is no access allowed to any of the registries defined in the top level registries configuration.

It is common for tooling, such as bundler, mix, pip, and swift, to allow the execution of external code by default.

In this example, the configuration file allows Dependabot to access the ruby-github private package registry. In the same updatessetting, insecure-external-code-executionis set to allow, which means that the code executed by dependencies will only access the ruby-github registry, and not the dockerhub registry.

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"

Supported private registries

Examples of how to configure access to the private registries supported by Dependabot.

cargo-registry

The cargo-registry type supports a token.

此注册表类型会与 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

The composer-repository type supports username and password. 如果帐户是 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 works with any container registries that implement the OCI container registry spec. For more information, see https://github.com/opencontainers/distribution-spec/blob/main/spec.md. Dependabot supports authentication to private registries via a central token service or HTTP Basic Auth. For further details, see Token Authentication Specification in the Docker documentation and Basic access authentication on Wikipedia.

The docker-registry type supports username and password. 如果帐户是 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

The docker-registry type can also be used to pull from private Amazon ECR using static AWS credentials.

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

The git type supports username and password. 如果帐户是 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

The goproxy-server type supports username and password. 如果帐户是 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}}

hex-organization

The hex-organization type supports organization and key.

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

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

hex-repository

The hex-repository type supports an authentication key.

repo is a required field, which must match the name of the repository used in your dependency declaration.

The public-key-fingerprint is an optional configuration field, representing the fingerprint of the public key for the Hex repository. public-key-fingerprint is used by Hex to establish trust with the private repository. The public-key-fingerprint field can be either listed in plaintext or stored as a Dependabot secret.

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

The maven-repository type supports username, password and 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

npm-registry

The npm-registry type supports username and password, or token. 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

When using username and password, your .npmrc's auth token may contain a base64 encoded _password; however, the password referenced in your Dependabot configuration file must be the original (unencoded) password.

注意

When using npm.pkg.github.com, don't include a path. Instead use the https://npm.pkg.github.com URL without a path.

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

For security reasons, Dependabot does not set environment variables. Yarn (v2 and later) requires that any accessed environment variables are set. When accessing environment variables in your .yarnrc.yml file, you should provide a fallback value such as ${ENV_VAR-fallback} or ${ENV_VAR:-fallback}. For more information, see Yarnrc files in the Yarn documentation.

nuget-feed

The nuget-feed type supports username and password, or token. 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

nuget-feed doesn't support the replaces-base parameter.

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

pub-repository

The pub-repository type supports a URL and a token.

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

The python-index type supports username and password, or token. 如果帐户是 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

rubygems-server

The rubygems-server type supports username and password, or token. 如果帐户是 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

The terraform-registry type supports a token.

YAML
registries:
  terraform-example:
    type: terraform-registry
    url: https://terraform.example.com
    token: ${{secrets.MY_TERRAFORM_API_TOKEN}}