This version of GitHub Enterprise Server was discontinued on 2024-09-25. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

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.

Who can use this feature?

Users with write access

In this article

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 configure Dependabot's access to private registries in the dependabot.yml file. The top-level registries key is optional and specifies authentication details.

There are 2 locations in the dependabot.yml file where you can use the registries key:

  • At the top level, where you define the registries and their access information, if needed.
  • Within the updates blocks, where you can use registries: "*" to tell Dependabot to use any or all of the registries you defined at the top level.
# 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"

You use the following options to specify access settings. Registry settings must contain a type and a url, and typically either a username and password combination or a token.

ParametersPurpose
REGISTRY_NAMERequired: Defines an identifier for the registry.
typeRequired: Identifies the type of registry.
Authentication detailsRequired: The parameters supported for supplying authentication details vary for registries of different types.
urlRequired: The URL to use to access the dependencies in this registry. The protocol is optional. If not specified, https:// is assumed. Dependabot adds or ignores trailing slashes as required.
replaces-baseIf the boolean value is true, Dependabot resolves dependencies using the specified url rather than the base URL of that ecosystem.

For more information about the configuration options that are available and about the supported types, see Dependabot options reference.

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 Troubleshooting Dependabot on GitHub Actions.

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

To create secrets for a personal account repository, you must be the repository owner. To create secrets for an organization repository, you must have admin access.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the "Security" section of the sidebar, select Secrets and variables, then click 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.

To create secrets at the organization level, you must have admin access.

  1. On GitHub, navigate to the main page of the organization.

  2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of the tabs in an organization's profile. The "Settings" tab is outlined in dark orange.

  3. In the "Security" section of the sidebar, select Secrets and variables, then click 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. 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.

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 registeries

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

composer-repository

The composer-repository type supports username and password. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

YAML
registries:
  github-octocat:
    type: git
    url: https://github.com
    username: x-access-token
    password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}

hex-organization

The hex-organization type supports organization and key.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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 and password. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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

npm-registry

The npm-registry type supports username and password, or token. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

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.

Note

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. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

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

python-index

The python-index type supports username and password, or token. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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. If the account is a GitHub account, you can use a GitHub personal access token in place of the password.

This registry type will prefix-match the path provided in the url option. This means you can provide multiple credentials to the same host, which can be used to access distinct paths. However, if you don't have multiple registries on the same host, we recommend that you omit the path from the url, so that all paths to the registry will receive credentials.

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