Developer automation

Integrating Dependabot

With GitHub Dependabot, you can automatically check for newer versions of your dependencies and update vulnerable dependencies.

This guide walks through the process of integrating GitHub Dependabot with Cloudsmith:

Configure authentication.
Enable Dependabot in GitHub.
Configure the Dependabot configuration file for your repository.
Verify the connection between Dependabot and Cloudsmith.

Note
Most of the examples in this guide walk through setup for a Maven repository, but the instructions apply to all supported formats.

Configure authentication

You can authenticate with Dependabot by using OpenID Connect (OIDC), or by adding your Cloudsmith username and API key as a repository secret in GitHub.

Configure OIDC authentication

To use OIDC authentication with Dependabot, you must create a service account and OIDC provider in Cloudsmith and then use the details of your service account when you configure the Dependabot configuration file for your repository.

Create a Cloudsmith service account.
Grant the service account Read access to your repository. For details, see Per-repository privileges.
Create an OIDC provider in Cloudsmith. Set the Provider URL to https://token.actions.githubusercontent.com, add a required aud claim matching https://github.com/YOUR-GITHUB-ORG, and in the Create provider settings form select your new service account from the SERVICE ACCOUNTS dropdown menu.

Configure API key authentication

You can use your Cloudsmith username and API key to authenticate with Dependabot by adding them to GitHub as repository secrets.

Copy your API key from Cloudsmith using the steps described in Getting your API key.
Go to the Settings tab of your repository on GitHub.
Click Secrets and variables, then select Dependabot.
Click New repository secret.
Add your Cloudsmith username as a secret. For example, in the Name field, enter CLOUDSMITH_USER_NAME, and in the Secret field, enter your Cloudsmith username.
Add your Cloudsmith API key as a secret. For example, in the Name field, enter CLOUDSMITH_API_KEY, and in the Secret field, enter your Cloudsmith API key.

Enable Dependabot in GitHub

To receive Dependabot alerts, you must first enable Dependabot alerts in your GitHub repository settings.

Go to the Security and quality tab of your repository on GitHub.
In the Overview section, click Enable Dependabot alerts. This opens the Settings > Security and quality > Advanced Security settings, where you can configure Dependabot for your repository.
In the Dependabot version updates section, click Enable. This opens an in-browser editor for a .github/dependabot.yml file that you'll configure in the next section.

Configure the Dependabot configuration file

For Dependabot to connect to Cloudsmith, you must specify the Cloudsmith connection details in .github/dependabot.yml.

Note
Dependabot's proxy only allows hosts listed in the top-level registries key. Cloudsmith redirects downloads to your download domain, so if it isn't listed in the registries block, Dependabot fails with a 403 (egress not allowlisted <host>) response.

In the top-level registries key, you must include an entry for both the native and download domains for your repository.

For example:

Native: https://maven.cloudsmith.io/YOUR-WORKSPACE/YOUR-REPO/
Download: https://dl.cloudsmith.io/basic/YOUR-WORKSPACE/YOUR-REPO/maven/

If you have an account-wide or per-repository custom domain, use it for both domain entries. For example:
- Native:
  - Account-wide: https://YOUR-NATIVE-DOMAIN/YOUR-REPO/
  - Per-repository: https://YOUR-NATIVE-DOMAIN/
- Download:
  - Account-wide:https://YOUR-DOWNLOAD-DOMAIN/basic/YOUR-REPO/maven/
  - Per-repository: https://YOUR-DOWNLOAD-DOMAIN/basic/maven/

Add the following configuration to .github/dependabot.yml:

Key	Location	Description
`registries`	Top level	Defines the Cloudsmith repository you're using. Each entry should include: - `type`: The type of repository. For example, `maven-repository`. - `url`: The URL of your Cloudsmith repository. - For API key authentication: `username` and `password`. - For OIDC authentication: `namespace`, `service-slug`, and `audience`. `api-host` is optional and defaults to `api.cloudsmith.io`. - `replaces-base`: This setting is optional and works hand in hand with Cloudsmith upstream Upstream proxying and caching. If `replaces-base` is set to `true`, Dependabot uses the specified Cloudsmith URL as the primary source for dependencies instead of the default public repository for that package ecosystem. This means you should configure a corresponding Cloudsmith upstream to ensure Dependabot checks Cloudsmith first for dependencies.
`updates`	Top level	Defines each `package-ecosystem` to update.
`package-ecosystem`	Under `updates`	Specify the package ecosystem you're using. For example, if you're using Maven, set `package-ecosystem` to `maven`.
`directory`	Under each `package-ecosystem` entry	Specify the directory where your package manifest is located. This is usually the root directory of your project.
`registries`	Under each `package-ecosystem` entry	Specify which of the top-level `registries` settings the `updates` configuration should apply to. You can use `registries: "*"` to tell Dependabot to use any or all of the registries you defined at the top level.
`schedule`	Under each `package-ecosystem` entry	Configure the schedule to define how often Dependabot should check for updates. You can set the interval to daily, weekly, or monthly.

For more information about using a top-level registries key to define access details for private registries, see the Dependabot options: Top-level registries key documentation.

Example dependabot.yml file for a Maven repository with OIDC authentication

To use the following example, replace:

YOUR-WORKSPACE with the name of your workspace
YOUR-REPO with the name of your repository
YOUR-SERVICE-SLUG with your Cloudsmith service slug
YOUR-GITHUB-ORG with your GitHub organization slug

yaml

version: 2
registries:

  cloudsmith-maven:
    type: maven-repository
    url: https://maven.cloudsmith.io/YOUR-WORKSPACE/YOUR-REPO/
    namespace: YOUR-WORKSPACE
    service-slug: YOUR-SERVICE-SLUG
    audience: https://github.com/YOUR-GITHUB-ORG
    replaces-base: true

  cloudsmith-maven-download:
    type: maven-repository
    url: https://dl.cloudsmith.io/basic/YOUR-WORKSPACE/YOUR-REPO/maven/
    namespace: YOUR-WORKSPACE
    service-slug: YOUR-SERVICE-SLUG
    audience: https://github.com/YOUR-GITHUB-ORG
    replaces-base: true

updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "daily"
    registries:
      - cloudsmith-maven
      - cloudsmith-maven-download
    commit-message:
      prefix: "deps"
    open-pull-requests-limit: 10

Example dependabot.yml file for a Maven repository with API key authentication

To use the following example, replace YOUR-WORKSPACE/YOUR-REPO with the name of your workspace and repository.

yaml

version: 2
registries:

  cloudsmith-maven:
    type: maven-repository
    url: https://maven.cloudsmith.io/YOUR-WORKSPACE/YOUR-REPO/
    username: "${{ secrets.CLOUDSMITH_USER_NAME }}"
    password: "${{ secrets.CLOUDSMITH_API_KEY }}"
    replaces-base: true

  cloudsmith-maven-download:
    type: maven-repository
    url: https://dl.cloudsmith.io/basic/YOUR-WORKSPACE/YOUR-REPO/maven/
    username: "${{ secrets.CLOUDSMITH_USER_NAME }}"
    password: "${{ secrets.CLOUDSMITH_API_KEY }}"
    replaces-base: true

updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "daily"
    registries:
      - cloudsmith-maven
      - cloudsmith-maven-download
    commit-message:
      prefix: "deps"
    open-pull-requests-limit: 10

Example dependabot.yml file for a npm repository with API key authentication

To use the following example, replace YOUR-WORKSPACE/YOUR-REPO with the name of your workspace and repository.

yaml

version: 2
registries:

  cloudsmith-npm:
    type: npm-registry
    url: https://npm.cloudsmith.io/YOUR-WORKSPACE/YOUR-REPO/
    username: "${{ secrets.CLOUDSMITH_USER_NAME }}"
    password: "${{ secrets.CLOUDSMITH_API_KEY }}"
    replaces-base: true

  cloudsmith-npm-download:
    type: npm-registry
    url: https://dl.cloudsmith.io/basic/YOUR-WORKSPACE/YOUR-REPO/npm/
    username: "${{ secrets.CLOUDSMITH_USER_NAME }}"
    password: "${{ secrets.CLOUDSMITH_API_KEY }}"

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    registries:
      - cloudsmith-npm
      - cloudsmith-npm-download
    commit-message:
      prefix: "deps"
    open-pull-requests-limit: 10

Warning
Dependabot uses only the first listed replaces-base: true entry as the default for npm. The download domain doesn't serve npm metadata, so you should only set replaces-base=true for the native domain, which should appear first in the registries block.

Verify the connection

To verify that Dependabot can successfully connect to Cloudsmith:

Go to the Insights tab of your repository on GitHub.
Select Dependency graph and then click the Dependabot tab.
Check for updates. You will find any errors here.

Dependabot checks for and updates dependencies via Cloudsmith, ensuring your dependencies are always up-to-date and secure.

Updated 5 days ago