Configuring Dependabot version updates

About version updates for dependencies

You enable Dependabot version updates by checking a dependabot.yml configuration file in to your repository's .github directory. Dependabot then raises pull requests to keep the dependencies you configure up-to-date. For each package manager's dependencies that you want to update, you must specify the location of the package manifest files and how often to check for updates to the dependencies listed in those files. For information about enabling security updates, see Configuring Dependabot security updates.

Beim ersten Aktivieren der Versionsaktualisierung sind möglicherweise viele Abhängigkeiten veraltet, und einige hinken der aktuellen Version um mehrere Versionen hinterher. Dependabot führt sofort nach der Aktivierung eine Überprüfung auf veraltete Abhängigkeiten durch. Abhängig davon, für wie viele Manifestdateien du Updates konfigurierst, werden dir möglicherweise schon wenige Minuten nach dem Hinzufügen der Konfigurationsdatei neue Pull Requests für Versionsaktualisierungen angezeigt. Dependabot führt auch bei späteren Änderungen an der Konfigurationsdatei eine Aktualisierung durch.

Damit die Pull Requests überschaubar bleiben und leicht überprüft werden können, löst Dependabot maximal fünf Pull Requests aus, um die Abhängigkeiten an die neueste Version anzupassen. Wenn einige der ersten Pull Requests vor der nächsten geplanten Aktualisierung gemergt werden, werden die verbleibenden Pull Requests beim nächsten Update geöffnet, bis zu diesem Höchstwert. Du kannst die maximale Anzahl offener Pull Requests ändern, indem du die open-pull-requests-limit-Konfigurationsoption festlegst.

Um die Anzahl von Pull Requests weiter zu verringern, kannst du mithilfe der Konfigurationsoption groups Abhängigkeiten (pro Paketökosystem) in Gruppen zusammenfassen. Dependabot löst dann einen einzigen Pull Request aus, um möglichst viele Abhängigkeiten in der Gruppe gleichzeitig auf die neuesten Versionen zu aktualisieren. For more information, see Optimieren der Erstellung von Pull Requests für Versionsupdates von Dependabot.

Aufgrund einer Fehlkonfiguration oder einer inkompatiblen Version kann es vorkommen, dass eine Ausführung von Dependabot fehlschlägt. Nach 15 fehlgeschlagenen Ausführungen überspringt Dependabot version updates nachfolgende geplante Ausführungen, bis du über das Abhängigkeitsdiagramm manuell eine Überprüfung auf Updates auslöst. Dependabot security updates wird weiterhin wie gewohnt ausgeführt.

By default only direct dependencies that are explicitly defined in a manifest are kept up to date by Dependabot version updates. You can choose to receive updates for indirect dependencies defined in lock files. For more information, see Controlling which dependencies are updated by Dependabot.

Bei der Durchführung von Sicherheits- oder Versionsupdates müssen einige Ökosysteme in der Lage sein, alle Abhängigkeiten von der jeweiligen Quelle aufzulösen, um zu überprüfen, ob die Updates erfolgreich waren. Wenn deine Manifest- oder Sperrdateien private Abhängigkeiten enthalten, muss Dependabot auf den Speicherort zugreifen können, an dem diese Abhängigkeiten gehostet werden. Organisationsbesitzer können Dependabot Zugriff auf private Repositorys gewähren, die Abhängigkeiten für ein Projekt innerhalb derselben Organisation enthalten. Weitere Informationen finden Sie unter Verwalten von Sicherheits- und Analyseeinstellungen für deine Organisation. Du kannst den Zugriff auf private Registrierungen in der Konfigurationsdatei dependabot.yml eines Repositorys konfigurieren. Weitere Informationen finden Sie unter Configuring access to private registries for Dependabot. Additionally, Dependabot doesn't support private GitHub dependencies for all package managers. For more information, see Von Dependabot unterstützte Ökosysteme und Repositorys and GitHub-Sprachunterstützung.

Enabling Dependabot version updates

You enable Dependabot version updates by committing a dependabot.yml configuration file to your repository. If you enable the feature in your settings page, GitHub creates a basic file which you can edit, otherwise you can create the file using any file editor.

1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

2. Klicke unter dem Repositorynamen auf Settings. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.

   

3. Klicke im Abschnitt „Security“ der Randleiste auf Advanced Security.

4. Under "Dependabot", to the right of "Dependabot version updates", click Enable to open a basic dependabot.yml configuration file in the .github directory of your repository. For information about the options you can use to customize how Dependabot maintains your repositories, see Referenz zu Dependabot-Optionen.

   YAML

   # To get started with Dependabot version updates, you'll need to specify which
   # package ecosystems to update and where the package manifests are located.
   
   version: 2
   updates:
   - package-ecosystem: "" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
   

5. Add a version. This key is mandatory. The file must start with version: 2.

6. Optionally, if you have dependencies in a private registry, add a registries section containing authentication details. For more information, see Configuring access to private registries for Dependabot.

7. Add an updates section, with an entry for each package manager you want Dependabot to monitor. This key is mandatory. You use it to configure how Dependabot updates the versions or your project's dependencies. Each entry configures the update settings for a particular package manager. For more information, see About the dependabot.yml file in "Dependabot options reference."

8. For each package manager, use:

   • package-ecosystem to specify the package manager. For more information about the supported package managers, see package-ecosystem.
   • directories or directory to specify the location of multiple manifest or other definition files. For more information, see Defining multiple locations for manifest files.
   • schedule.interval to specify how often to check for new versions.

9. Überprüfe die Konfigurationsdatei dependabot.yml im .github-Verzeichnis des Repositorys.

Example dependabot.yml file

The example dependabot.yml file below configures version updates for three package managers: npm, Docker, and GitHub Actions. When this file is checked in, Dependabot checks the manifest files on the default branch for outdated dependencies. If it finds outdated dependencies, it will raise pull requests against the default branch to update the dependencies.

# Basic `dependabot.yml` file with
# minimum configuration for three package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

  # Enable version updates for GitHub Actions
  - package-ecosystem: "github-actions"
    # Workflow files stored in the default location of `.github/workflows`
    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
    directory: "/"
    schedule:
      interval: "weekly"

# Basic `dependabot.yml` file with
# minimum configuration for three package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

  # Enable version updates for GitHub Actions
  - package-ecosystem: "github-actions"
    # Workflow files stored in the default location of `.github/workflows`
    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
    directory: "/"
    schedule:
      interval: "weekly"

In the example above, if the Docker dependencies were very outdated, you might want to start with a daily schedule until the dependencies are up-to-date, and then drop back to a weekly schedule.

Enabling version updates on forks

If you want to enable version updates on forks, there's an extra step. Version updates are not automatically enabled on forks when a dependabot.yml configuration file is present. This ensures that fork owners don't unintentionally enable version updates when they pull changes including a dependabot.yml configuration file from the original repository.

On a fork, you also need to explicitly enable Dependabot.

1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

2. Klicke unter dem Repositorynamen auf Settings. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.

   

3. Klicke im Abschnitt „Security“ der Randleiste auf Advanced Security.

4. Under "Dependabot," to the right of "Dependabot version updates," click Enable to allow Dependabot to initiate version updates.

Checking the status of version updates

After you enable version updates, the Dependabot tab in the dependency graph for the repository is populated. This tab shows which package managers Dependabot is configured to monitor and when Dependabot last checked for new versions.

For information, see Listing dependencies configured for version updates.

Disabling Dependabot version updates

You can disable version updates entirely by deleting the dependabot.yml file from your repository. More usually, you want to disable updates temporarily for one or more dependencies, or package managers.

• Package managers: disable by setting open-pull-requests-limit: 0 or by commenting out the relevant package-ecosystem in the configuration file.
• Specific dependencies: disable by adding ignore attributes for packages or applications that you want to exclude from updates.

When you disable dependencies, you can use wild cards to match a set of related libraries. You can also specify which versions to exclude. This is particularly useful if you need to block updates to a library, pending work to support a breaking change to its API, but want to get any security fixes to the version you use.

Example disabling version updates for some dependencies

The example dependabot.yml file below includes examples of the different ways to disable updates to some dependencies, while allowing other updates to continue.

# `dependabot.yml` file with updates
# disabled for Docker and limited for npm

version: 2
updates:
  # Configuration for Dockerfile
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
      # Disable all pull requests for Docker dependencies
    open-pull-requests-limit: 0

  # Configuration for npm
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      # Ignore updates to packages that start with 'aws'
      # Wildcards match zero or more arbitrary characters
      - dependency-name: "aws*"
      # Ignore some updates to the 'express' package
      - dependency-name: "express"
        # Ignore only new versions for 4.x and 5.x
        versions: ["4.x", "5.x"]
      # For all packages, ignore all patch updates
      - dependency-name: "*"
        update-types: ["version-update:semver-patch"]

For more information about checking for existing ignore preferences, see Referenz zu Dependabot-Optionen.