Using the dependency submission API

About the dependency submission API

You can use the REST API to submit dependencies for a project. This enables you to add dependencies, such as those resolved when software is compiled or built, to GitHub's dependency graph feature, providing a more complete picture of all of your project's dependencies.

The dependency graph shows any dependencies you submit using the API in addition to any dependencies that are identified from manifest or lock files in the repository (for example, a package-lock.json file in a JavaScript project). For more information about viewing the dependency graph, see Exploring the dependencies of a repository.

Submitted dependencies will receive Dependabot alerts and Dependabot security updates for any known vulnerabilities. You will only get Dependabot alerts for dependencies that are from one of the supported ecosystems for the GitHub Advisory Database. For more information about these ecosystems, see About the GitHub Advisory database. For transitive dependencies submitted via the dependency submission API, Dependabot will automatically open pull requests to update the parent dependency, if an update is available.

Submitted dependencies will not be surfaced in dependency review or your organization's dependency insights.

Dependencies are submitted to the dependency submission 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 your dependencies detected at build time or from a software bill of materials (SBOM). There are GitHub Actions that support either of these use cases. For more information about the dependency submission API, see REST API endpoints for dependency submission.

Submitting dependencies at build-time

You can use the dependency submission API in a GitHub Actions workflow to submit dependencies for your project when your project is built.

Using pre-made actions

The simplest way to use the dependency submission API is by adding a pre-made action to your repository that will gather and convert the list of dependencies to the required snapshot format and submit the list to the API.

For more information about these actions, see Dependency graph supported package ecosystems.

Creating your own action

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

Generate a list of dependencies for your project.
Translate the list of dependencies into the snapshot format accepted by the dependency submission API. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in REST API endpoints for dependency submission.
Submit the formatted list of dependencies to the dependency submission API.

GitHub Enterprise Server maintains the Dependency Submission Toolkit, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the dependency submission API. For more information about writing an action, see Sharing automations.

Generating and submitting a software bill of materials (SBOM)

An SBOM is a formal, machine-readable inventory of a project's dependencies and associated information (such as versions and package identifiers). SBOMs help reduced supply chain risks by:

providing transparency about the dependencies used by your repository
allowing vulnerabilities to be identified early in the process
providing insights in the license compliance, security, or quality issues that may exist in your codebase
enabling you to better comply with various data protection standards

Generating a software bill of materials (SBOM)

To generate an SBOM, you can use:

The GitHub UI. For more information about how to export an SBOM for a repository using information from the dependency graph, see Exporting a software bill of materials for your repository.
The REST API. For more information, see REST API endpoints for software bill of materials (SBOM).
GitHub Actions. The following actions will generate an SBOM for your repository and attach it as a workflow artifact which you can download and use in other applications. For more information about downloading workflow artifacts, see Downloading workflow artifacts.

Action	Details
Anchore SBOM Action	Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems
sbom-tool by Microsoft	Scans your dependencies and creates an SPDX compatible SBOM

Submitting a software bill of materials (SBOM) to the dependency submission API

To receive Dependabot alerts for dependencies that have known vulnerabilities, you can upload and submit the SBOM to the dependency submission API. To submit an SBOM to the dependency submission API, you can use one of the actions in the following table.

Tip

The SPDX Dependency Submission Action and the Anchore SBOM Action can be used to both generate the SBOM and submit it to the dependency submission API.

Action	Details
SPDX Dependency Submission Action	Uses Microsoft's SBOM Tool to create SPDX 2.2 compatible SBOMs with the supported ecosystems
Anchore SBOM Action	Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems
SBOM Dependency Submission Action	Uploads a CycloneDX SBOM to the dependency submission API

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 dependency submission API.


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@v4
    - 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@v3
      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/"

In this article