About configuring private registries for Dependabot
This article contains recommendations and advice to help you configure Dependabot to access your private registry, along with:
- Detailed snippets of the
dependabot.yml
configuration file for each package manager. - Important limitations or caveats.
- Steps explaining how to test that the configuration is working.
- Extra configuration options, wherever appropriate (for example, npm has a configuration file that needs to be set).
- Advice about configuring registry hosts.
You'll find detailed guidance for the setup of the following package managers:
You'll also find recommendations for the setup of the following registry hosts:
Configuring package managers
Bundler
Supported by Artifactory, Artifacts, Cloudsmith, GitHub Packages registry, Nexus, and ProGet.
You can authenticate with either a username and password, or a token. For more information, see rubygems-server
in "Configuration options for the dependabot.yml file."
Snippet of a dependabot.yml
file using a username and password.
registries:
ruby-example:
type: rubygems-server
url: https://rubygems.example.com
username: octocat@example.com
password: ${{secrets.MY_RUBYGEMS_PASSWORD}}
The snippet of dependabot.yml
file below uses a token. For this type of registry using the GitHub Packages registry
(xyz.pkg.github.com
), the token is in fact a GitHub personal access token (PAT) .
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
Notes
Dependencies sourced directly from a GitHub repository give Dependabot access to the repository through the GitHub UI. For information about allowing Dependabot to access private GitHub dependencies, see "Allowing Dependabot to access private dependencies."
Cargo
Cargo supports username, password and token-based authentication. For more information, see cargo-registry
in "Configuration options for the dependabot.yml file."
The snippet below shows a dependabot.yml
file configuration that uses a token.
registries:
cargo-example:
type: cargo-registry
registry: "name-of-your-registry"
url: https://cargo.cloudsmith.io/foobaruser/test/
token: "Token ${{secrets.CARGO_TOKEN}}"
We tested this configuration against the https://cargo.cloudsmith.io
private registry.
Docker
Docker supports using a username and password for registries. For more information, see docker-registry
in "Configuration options for the dependabot.yml file."
Snippet of dependabot.yml
file using a username and password.
registries:
dockerhub:
type: docker-registry
url: https://registry.hub.docker.com
username: octocat
password: ${{secrets.MY_DOCKERHUB_PASSWORD}}
docker-registry
can also be used to pull from private Amazon ECR using static AWS credentials.
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}}
Notes
Dependabot works with any container registries that implement the Open Container Initiative (OCI) Distribution Specification. 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 more information, see Token Authentication Specification in the Docker documentation and Basic access authentication on Wikipedia.
Limitations and workarounds
- Image names may not always be detected in Containerfiles, Helm files, or yaml files.
- Dockerfiles may only receive a version update to the first
FROM
directive. - Dockerfiles do not receive updates to images specified with the
ARG
directive. There is a workaround available for theCOPY
directive. For more information, see "Dependabot ignores image references in COPY Dockerfile statement" in thedependabot/dependabot-core
repository. - Dependabot doesn't support multi-stage Docker builds. For more information, see "Support for Docker multi-stage builds" in the
dependabot/dependabot-core
repository.
Gradle
Dependabot doesn't run Gradle but supports updates to certain Gradle files. For more information, see "Gradle" in "Configuration options for the dependabot.yml file."
Gradle supports the maven-repository
registry type. For more information, see maven-repository
in "Configuration options for the dependabot.yml file."
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.
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:
- gradle-artifactory
schedule:
interval: "monthly"
Notes
You may not see all of your dependencies represented in the dependency graph, especially if some dependencies are build-time dependencies. You can use the dependency submission API to inform GitHub about your other dependencies, and receive security updates for them. For more information, see "Using the dependency submission API."
Maven
Maven supports username and password authentication. For more information, see maven-repository
in "Configuration options for the dependabot.yml file."
registries:
maven-artifactory:
type: maven-repository
url: https://acme.jfrog.io/artifactory/my-maven-registry
username: octocat
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
If the account is a GitHub account, you can use a GitHub personal access token in place of the password.
version: 2
registries:
maven-github:
type: maven-repository
url: https://maven.pkg.github.com/octocat
username: octocat
password: ${{secrets.OCTOCAT_GITHUB_PAT}}
updates:
- package-ecosystem: "maven"
directory: "/"
registries:
- maven-github
schedule:
interval: "monthly"
Notes
You may not see all of your dependencies represented in the dependency graph, especially if some dependencies are build-time dependencies. You can use the dependency submission API to inform GitHub about your other dependencies, and receive security updates for them. For more information, see "Using the dependency submission API."
npm
You can define the configuration in the dependabot.yml
file using the npm-registry
type, or configure Dependabot to send all registry requests through a specified base URL.
Using the npm-registry
type in the configuration file
You can define the private registry configuration in a dependabot.yml
file using the npm-registry
type. For more information, see "Configuration options for the dependabot.yml file."
The snippet of a dependabot.yml
file below uses a token. For this type of registry using the GitHub Packages registry
(xyz.pkg.github.com
), the token is in fact a GitHub personal access token (PAT) .
registries:
npm-github:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
The npm ecosystem requires a .npmrc
file with the private registry URL to be checked into the repository.
Example of the content of a .npmrc
file:
registry=https://<private-registry-url>
Alternatively you can add the private registry URL to an existing .npmrc
file using the following command.
npm config set registry <url>
For more information, see registry in the npm documentation.
You can also scope the configuration to only a single dependency or organization, in which case the token will only be valid for the organization, and different tokens can be used for different organizations for the same repository.
npm config set @<org-name>:registry <url>
This would result in a '.npmrc' with the registry:
@<org-name>:registry=https://<private-registry-url>
npm can be configured to use the private registry's URL in lockfiles with replace-registry-host
. For more information, see replace-registry-host in the npm documentation.
npm config set replace-registry-host "never"
If you use replace-registry-host
, you must locally run npm install
in order to regenerate the lockfile to use the private registry URL. Dependabot will use the same URL when providing updates.
Once the registry is configured, you can also run npm login
to verify that your configuration is correct and valid. The lockfile can also be regenerated to use the new private registry by running npm install
again.
You need to ensure that the .npmrc
file is checked into the same directory as the project's package.json
and that the file doesn't include any environment variables or secrets.
If you use a monorepo, the .npmrc
file should live in the project's root directory.
Configuring Dependabot to send registry requests through a specified base URL
You can configure Dependabot to send all registry requests through a specified base URL. In order for Dependabot to access a public dependency, the registry must either have a cloned copy of the dependency with the requested version, or allow traffic to fetch from a public registry if the dependency is not available.
If there is no global registry defined in a .npmrc
file, you can set replaces-base
to true
in the dependabot.yml
file. For more information, see "replaces-base
" in "Configuration options for the dependabot.yml file."
Notes
Dependencies sourced directly from a GitHub repository give Dependabot access to the repository through the GitHub UI. For information about allowing Dependabot to access private GitHub dependencies, see "Allowing Dependabot to access private dependencies."
For scoped dependencies (@my-org/my-dep
), Dependabot requires that the private registry is defined in the project's .npmrc
file. To define private registries for individual scopes, use @myscope:registry=https://private_registry_url
.
Registries should be configured using the https
protocol.
NuGet
Supported by Artifactory, Artifacts, Cloudsmith, GitHub Packages registry, Nexus, and ProGet.
The nuget-feed
type supports username and password, or token. For more information, see nuget-feed
in "Configuration options for the dependabot.yml file."
registries:
nuget-example:
type: nuget-feed
url: https://nuget.example.com/v3/index.json
username: octocat@example.com
password: ${{secrets.MY_NUGET_PASSWORD}}
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}}
Notes
You can also use a token in your dependabot.yml
file. For this type of registry using the GitHub Packages registry
(xyz.pkg.github.com
), the token is in fact a GitHub personal access token (PAT) .
registries:
nuget-azure-devops:
type: nuget-feed
url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json
token: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}
pub
You can define the private registry configuration in a dependabot.yml
file using the pub-repository
type. For more information, see "Configuration options for the dependabot.yml file."
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
Notes
Dependencies sourced directly from a GitHub repository give Dependabot access to the repository through the GitHub UI. For information about allowing Dependabot to access private GitHub dependencies, see "Allowing Dependabot to access private dependencies."
pub supports URL and token authentication. The URL used for the registry should match the pub-hosted URL. For more information, see Hosted Pub Repository Specification Version 2 in the github/dart-lang/pub
repository.
Dependabot doesn't support overrides to the default package registry. For more information about overrides and why some users may implement them, see Overriding the default package repository in the Dart documentation.
Python
Supported by Artifactory, Azure Artifacts, Cloudsmith, Nexus, and ProGet. The GitHub Packages registry is not supported.
The python-index
type supports username and password, or token. For more information, see python-index
in "Configuration options for the dependabot.yml file."
registries:
python-example:
type: python-index
url: https://example.com/_packaging/my-feed/pypi/example
username: octocat
password: ${{secrets.MY_BASIC_AUTH_PASSWORD}}
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}}
registries:
python-gemfury:
type: python-index
url: https://pypi.fury.io/my_org
token: ${{secrets.MY_GEMFURY_TOKEN}}
Notes
Dependencies sourced directly from a GitHub repository give Dependabot access to the repository through the GitHub UI. For information about allowing Dependabot to access private GitHub dependencies, see "Allowing Dependabot to access private dependencies."
url
should contain the URL, organization, and the "feed" or repository.
Yarn
The Yarn registry uses a configuration similar to that of the npm registry. For more information, see "npm-registry
" in "Configuration options for the dependabot.yml file."
registries:
yarn-github:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
- For private registries, you have to check in a
.yarnrc.yml
file (for Yarn 3) or a.yarnrc
file (for Yarn Classic). - The yarn config files should not contain environment variables.
- You should configure private registries listed in the
dependabot.yml
file usinghttps
.
Yarn Classic
You can either specify the private registry configuration in the dependabot.yml
file, or set up Yarn Classic according to the standard package manager instructions.
Defining the private registry configuration in the dependabot.yml
file
You can define the private registry configuration in your dependabot.yml
file. For more information, see "Configuration options for private registries" in "Configuration options for the dependabot.yml file."
To ensure that the private registry is listed as the dependency source in the project's yarn.lock
file, you need to run yarn install
on a machine with private registry access. Yarn should update the resolved field to include the private registry URL.
encoding@^0.1.11:
version "0.1.13"
resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9"
integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==
dependencies:
iconv-lite "^0.6.2"
Following the standard instructions from your package manager
If the yarn.lock
file doesn't list the private registry as the dependency source, you can set up Yarn Classic according to the standard package manager instructions.
-
Define the private registry configuration in the
dependabot.yml
file. -
You can then either:
- Manually set the private registry to the
.yarnrc
file by adding the registry to a.yarnrc.yml
file in the project root with the key registry, or - Perform the same action by running
yarn config set registry <private registry URL>
in your terminal.
Example of a
.yarnrc
with a private registry defined:registry https://nexus.example.com/repository/yarn-all
- Manually set the private registry to the
Yarn Berry (v3)
For information on the configuration, see Settings (.yarnrc.yml) in the Yarn documentation.
As with Yarn Classic, you can either specify the private registry configuration in the dependabot.yml
file, or set up Yarn Berry according to the package manager instructions.
Defining the private registry configuration in the dependabot.yml
file
You can define the private registry configuration in your dependabot.yml
file. For more information, see "Configuration options for private registries" in "Configuration options for the dependabot.yml file."
To ensure the private registry is listed as the dependency source in the project's yarn.lock
file, run yarn install
on a machine with private registry access. Yarn should update the resolved field to include the private registry URL.
encoding@^0.1.11:
version "0.1.13"
resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9"
integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==
dependencies:
iconv-lite "^0.6.2"
You can also configure private registries with npmAuthIdent
or npmAuthToken
. For more information, see "npmAuthIdent" and "npmAuthToken" in the Yarn documentation.
yarn config set registry <url>
You can scope the configuration to only cover a single dependency or organization.
yarn config set @<SCOPE>:registry <url>
Finally, we recommend you run yarn login
to verify that your configuration is correct and valid. The lockfile can also be regenerated to use the new private registry by running yarn install
again.
Following the standard instructions from your package manager
If the yarn.lock
file doesn't list the private registry as the dependency source, you can set up Yarn Berry according to the standard package manager instructions.
-
Define the private registry configuration in the
dependabot.yml
file. -
You can then either:
- Manually set the private registry to the
.yarnrc
file by adding the registry to a.yarnrc.yml
file in the project root with the keynpmRegistryServer
, or - Perform the same action by running
yarn config set npmRegistryServer <private registry URL>
in your terminal.
Example of a
.yarnrc.yml
file with a private registry configured:npmRegistryServer: "https://nexus.example.com/repository/yarn-all"
For more information, see npmRegistryServer in the Yarn documentation.
- Manually set the private registry to the
Notes
Dependencies sourced directly from a GitHub repository give Dependabot access to the repository through the GitHub UI. For information about allowing Dependabot to access private GitHub dependencies, see "Allowing Dependabot to access private dependencies."
For scoped dependencies (@my-org/my-dep
), Dependabot requires that the private registry is defined in the project's .yarnrc file
. To define private registries for individual scopes, use @myscope:registry" "https://private_registry_url"
.
Configuring private registry hosts
Artifactory
For information about the configuration of Artifactory, see Configuring Artifactory in the JFrog Artifactory documentation.
Remote repositories
Remote repositories serve as a cache for build artifacts and dependencies. Instead of having to reach out to a global dependency repository, your build tool can use the artifactory cache, which will speed up build times. For more information, see Remote Repositories in the JFrog Artifactory documentation.
If you use the replace-base
setting, you should also configure a remote repository for Artifactory if you want Dependabot to access another registry whenever the dependency isn't found in the private registry.
Virtual registry
You can use a virtual registry to group together all private and public dependencies under a single domain. For more information, see npm Registry in the JFrog Artifactory documentation.
Azure Artifacts
For information about Azure Artifacts and instructions on how to configure Dependabot to work with Azure Artifacts, see Azure DevOps in the Azure Artifacts documentation, and Use Dependabot in GitHub with Azure Artifacts, respectively.
Example of Azure Artifacts registry:
registries:
nuget-azure-devops:
type: nuget-feed
url: https://pkgs.dev.azure.com/my_org/_packaging/public/nuget/v3/index.json
token: ${{secrets.AZURE_DEVOPS_TOKEN}}
The Azure Artifacts password must be an unencoded token and should include a :
after the token. In addition, the password cannot be base64-encoded.
You can check whether the private registry is successfully accessed by looking at the Dependabot logs.
Cloudsmith
For information about Cloudsmith and instructions on how to configure Dependabot to work with Cloudsmith, see Getting Started with Cloudsmith and Integrate GitHub Dependabot with Cloudsmith in the Cloudsmith documentation.
GitHub Packages registry
For information about GitHub Packages registries, see "Working with a GitHub Packages registry." From that article, you can access pages describing how to configure the following registries.
- Bundler (rubygems)
- Docker (containers)
- GitHub Actions
- Gradle
- Maven
- Npm
- NuGet
- Yarn
registries:
github:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{ secrets.<token> }}
Notes
There is no Python container registry.
For private registries that are scoped to a particular organization, Dependabot expects the URL to include the organization name in the dependabot.yml
file.
Nexus
For information about the configuration of Nexus, see Repository Manager 3 in the Sonatype documentation.
Notes
With Nexus Repository Pro, you can enable user tokens. For more information, see User Tokens in the Sonatype documentation.
Example of Nexus registry:
registries:
npm-nexus:
type: npm-registry
url: https://registry.example.com/repository/npm-internal/
token: ${{secrets.NEXUS_NPM_TOKEN}}
If you are running Nexus behind a reverse proxy, you need to ensure that the server is accessible using an Auth token by using curl -v -H 'Authorization: Bearer <token>' 'https://<nexus-repo-url>/repository/<repo-name>/@<scope>%2<package>'
. For more information, see Run Behind a Reverse Proxy in the Sonatype documentation.
If you are restricting which IPs can reach your Nexus host, you need to add the Dependabot IPs to the allowlist.
- You can find the IP addresses Dependabot uses to access the registry in the meta API endpoint, under the dependabot key. For more information, see "REST API endpoints for meta data."
- These are the current IPs:
- "18.213.123.130/32"
- "3.217.79.163/32"
- "3.217.93.44/32" For more information, see Securing Nexus Repository Manager in the Sonatype documentation.
Registries can be proxied to reach out to a public registry in case a dependency is not available in the private registry. However, you may want Dependabot to only access the private registry and not access the public registry at all. For more information, see "Quick Start Guide - Proxying Maven and NPM" in the Sonatype documentation, and "Removing Dependabot access to public registries."
ProGet
For information about ProGet and instructions on how to configure Dependabot to work with feeds in ProGet, see the ProGet documentation.
Example of ProGet registry configuration for a NuGet feed:
registries:
proget-nuget-feed:
type: nuget-feed
url: https://proget.corp.local/nuget/MyNuGetFeed/v3/index.json
token: ${{secrets.PROGET_APK_KEY}}
Example of ProGet registry configuration for Bundler (rubygems):
registries:
proget-gems-feed:
type: rubygems-server
url: https://proget.corp.local/rubygems/MyRubygemsFeed
token: ${{secrets.PROGET_APK_KEY}}
Example of ProGet registry configuration for Python (PyPI):
registries:
proget-python-feed:
type: python-index
url: https://proget.corp.local/pypi/MyPythonFeed
token: ${{secrets.PROGET_APK_KEY}}
Notes
The token
should be an API Key with access to view packages. For more information, see API Access and API Keys in the ProGet documentation.
You can check whether the private registry is successfully accessed by looking at the Dependabot logs.