docs/content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md

title, intro, shortTitle, topics, versions

title	intro	shortTitle	topics	versions
Using the dependency submission API	You can use the {% data variables.dependency-submission-api.name %} to submit dependencies for projects, such as the dependencies resolved when a project is built or compiled.	Dependency submission API	API Dependency graph Dependencies REST	feature dependency-submission-api

{% data reusables.dependency-submission.dependency-submission-api-beta %}

About the {% data variables.dependency-submission-api.name %}

{% data reusables.dependency-submission.about-dependency-submission %}

Dependencies are submitted to the {% data variables.dependency-submission-api.name %} 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 {% data variables.product.prodname_actions %} that support either of these use cases. For more information about the {% data variables.dependency-submission-api.name %}, see "AUTOTITLE."

Submitting dependencies at build-time

You can use the {% data variables.dependency-submission-api.name %} in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built.

Using pre-made actions

The simplest way to use the {% data variables.dependency-submission-api.name %} 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. Actions that complete these steps for various ecosystems are available on {% data variables.product.prodname_marketplace %}. Some of these actions are provided by third parties. You can find links to the currently available actions in the table below.

Ecosystem	Action	Maintained by {% data variables.product.prodname_dotcom %}
Go	Go Dependency Submission	{% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %}
Gradle	Gradle Dependency Submission	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}
Maven	Maven Dependency Tree Dependency Submission	{% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %}
Mill	Mill Dependency Submission	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}
Scala	Sbt Dependency Submission	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}
NuGet and others	Component Detection dependency submission action	{% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %}

{% note %}

Note: For the Component Detection dependency submission action, other supported ecosystems include Vcpkg, Conan, Conda, Crates, as well as NuGet.

{% endnote %}

For example, the following Go Dependency Submission workflow calculates the dependencies for a Go build-target (a Go file with a main function) and submits the list to the {% data variables.dependency-submission-api.name %}.

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: {% data reusables.actions.action-checkout %}

      - uses: {% data reusables.actions.action-setup-go %}
        with:
          go-version: ">=1.18.0"

      - name: Run snapshot action
        uses: actions/go-dependency-submission@v1
        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

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 {% data variables.dependency-submission-api.name %}. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in "AUTOTITLE."
3. Submit the formatted list of dependencies to the {% data variables.dependency-submission-api.name %}.

{% data variables.product.product_name %} maintains the Dependency Submission Toolkit, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the {% data variables.dependency-submission-api.name %}. For more information about writing an action, see "AUTOTITLE".

Generating and submitting a software bill of materials (SBOM)

{% data reusables.dependency-graph.sbom-intro %}

{% ifversion dependency-graph-sbom-export %} To generate an SBOM, you can use:

• the {% data variables.product.prodname_dotcom %} user interface. For more information about how to export an SBOM for a repository using information from the dependency graph, see "AUTOTITLE."
• the REST API. For more information, see "AUTOTITLE."
• {% data variables.product.prodname_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 "AUTOTITLE." {% else %} You can use {% data variables.product.prodname_actions %} to generate an SBOM. 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 "AUTOTITLE." {% endif %}

Action	Details	Maintained by {% data variables.product.prodname_dotcom %}
SBOM-generator-action	Uses the information in your dependency graph to generate an SPDX SBOM	{% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %}
Anchore SBOM Action	Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}
sbom-tool by Microsoft	Scans your dependencies and creates an SPDX compatible SBOM	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}

You can then upload and submit the SBOM to the {% data variables.dependency-submission-api.name %} using one of the following actions so that you can receive {% data variables.product.prodname_dependabot_alerts %} on any dependencies that have known vulnerabilities. Actions that appear in both tables can be configured to both generate and submit an SBOM.

Action	Details	Maintained by {% data variables.product.prodname_dotcom %}
SPDX Dependency Submission Action	Uses Microsoft's SBOM Tool to create SPDX 2.2 compatible SBOMs with the supported ecosystems	{% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %}
Anchore SBOM Action	Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}
SBOM Dependency Submission Action	Uploads a CycloneDX SBOM to the {% data variables.dependency-submission-api.name %}	{% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %}

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 {% data variables.dependency-submission-api.name %}.

name: SBOM upload

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

jobs:
  SBOM-upload:

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

    steps:
    - uses: {% data reusables.actions.action-checkout %}
    - 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 ${{ github.repository }} -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
    - uses: {% data reusables.actions.action-upload-artifact %}
      with:
        name: sbom
        path: _manifest/spdx_2.2
    - name: SBOM upload
      uses: advanced-security/spdx-dependency-submission-action@v0.0.1
      with:
        filePath: "_manifest/spdx_2.2/"