Using the dependency submission API

About the Abhängigkeitsübermittlungs-API

Du kannst die REST-API verwenden, um Abhängigkeiten für ein Projekt zu übermitteln. Dadurch kannst du Abhängigkeiten wie die, die beim Kompilieren oder Erstellen von Software aufgelöst werden, zum Abhängigkeitsdiagrammfeature von GitHub hinzufügen und ein vollständigeres Bild aller Abhängigkeiten deines Projekts bieten.

Das Abhängigkeitsdiagramm zeigt alle Abhängigkeiten, die du mithilfe der API übermittelst, zusätzlich zu allen Abhängigkeiten, die von Manifest- oder Sperrdateien im Repository aus identifiziert werden (z. B. eine package-lock.json-Datei in einem JavaScript-Projekt). Weitere Informationen zur Anzeige des Abhängigkeitsdiagramms findest du unter Exploring the dependencies of a repository.

Übermittelte Abhängigkeiten erhalten Dependabot alerts und Dependabot security updates für alle bekannten Sicherheitsrisiken. Sie erhalten Dependabot alerts nur für Abhängigkeiten, die aus einem der unterstützten Ökosysteme für GitHub Advisory Database stammen. Weitere Informationen zu diesen Ökosystemen findest du unter Informationen zu GitHub Advisory Database. Für transitive Abhängigkeiten, die über die Abhängigkeitsübermittlungs-API übermittelt werden, öffnet Dependabot automatisch Pull Requests, um die übergeordnete Abhängigkeit zu aktualisieren, wenn ein Update verfügbar ist.

Übermittelte Abhängigkeiten werden in der Abhängigkeitsüberprüfung angezeigt, aber sind nicht in den Abhängigkeitserkenntnissen deiner Organisation verfügbar.

Dependencies are submitted to the Abhängigkeitsübermittlungs-API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from the dependencies detected at build time. For technical details on using the Abhängigkeitsübermittlungs-API over the network, see REST-API-Endpunkte für die Abhängigkeitsübermittlung.

Submitting dependencies at build-time

You can use the Abhängigkeitsübermittlungs-API in a GitHub Actions workflow to submit dependencies for your project when your project is built.

Using pre-made actions

Am einfachsten lässt sich die Abhängigkeitsübermittlungs-API verwenden, indem du deinem Repository eine vordefinierte Aktion hinzuzufügst, die die Liste der Abhängigkeiten erfasst, in das erforderliche Momentaufnahmeformat konvertiert und an die API übermittelt.

Ökosystem	Aktion
Go	Go-Abhängigkeitsübermittlung
Gradle	Gradle Dependency Submission
Maven	Maven Dependency Tree Dependency Submission
Mühle	Mill Dependency Submission
Mix (Elixir)	Mix Dependency Submission
Scala	Sbt Dependency Submission
NuGet und andere	Aktion zur Übermittlung von Abhängigkeiten bei der Komponentenerkennung

Der folgende Workflow für die Go-Abhängigkeitsübermittlung berechnet beispielsweise die Abhängigkeiten für ein Go-Buildziel (eine Go-Datei mit einer main-Funktion) und sendet die Liste an die Abhängigkeitsübermittlungs-API.

name: Go Dependency Submission
on:
  push:
    branches:
      - main

# The API requires write permission on the repository to submit dependencies
permissions:
  contents: write

# Environment variables to configure Go and Go modules. Customize as necessary
env:
  GOPROXY: '' # A Go Proxy server to be used
  GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
jobs:
  go-action-detection:
    runs-on: ubuntu-latest
    steps:
      - name: 'Checkout Repository'
        uses: actions/checkout@v5

      - uses: actions/setup-go@v5
        with:
          go-version: ">=1.18.0"

      - name: Run snapshot action
        uses: actions/go-dependency-submission@v2
        with:
            # Required: Define the repo path to the go.mod file used by the
            # build target
            go-mod-path: go-example/go.mod
            #
            # Optional. Define the repo path of a build target,
            # a file with a `main()` function.
            # If undefined, this action will collect all dependencies
            # used by all build targets for the module. This may
            # include Go dependencies used by tests and tooling.
            go-build-target: go-example/cmd/octocat.go

For more information about these actions, see Abhängigkeitsdiagramm unterstützte Paket-Ökosysteme.

Creating your own action

Alternatively, you can write your own action to submit dependencies for your project at build-time. Your workflow should:

1. Generate a list of dependencies for your project.
2. Translate the list of dependencies into the snapshot format accepted by the Abhängigkeitsübermittlungs-API. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in REST-API-Endpunkte für die Abhängigkeitsübermittlung.
3. Submit the formatted list of dependencies to the Abhängigkeitsübermittlungs-API.

GitHub maintains the Dependency Submission Toolkit, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the Abhängigkeitsübermittlungs-API. For more information about writing an action, see Wiederverwenden von Automatisierungen.

Submitting SBOMs as snapshots

If you have external tools which create or manage Software Bills of Materials (SBOMs), you can also submit those SBOMs to the Abhängigkeitsübermittlungs-API. The snapshot data format is very similar to the standard SPDX and CycloneDX SBOM formats, and there are several tools which can generate or translate formats for use as snapshots.

For example, the following SPDX Dependency Submission Action workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the Abhängigkeitsübermittlungs-API.

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.
name: SBOM upload

on:
  workflow_dispatch:
  push:
    branches: ["main"]

jobs:
  SBOM-upload:

    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write

    steps:
    - uses: actions/checkout@v5
    - name: Generate SBOM
      # generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
      run: |
        curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
        chmod +x $RUNNER_TEMP/sbom-tool
        $RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
    - uses: actions/upload-artifact@v4
      with:
        name: sbom
        path: _manifest/spdx_2.2
    - name: SBOM upload
      uses: advanced-security/spdx-dependency-submission-action@5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e
      with:
        filePath: "_manifest/spdx_2.2/"