Using the dependency submission API

About the 依赖项提交 API

可以使用 REST API 提交项目的依赖项。 这使你可以将依赖项（如编译或生成软件时解析的依赖项）添加到 GitHub 的依赖项关系图功能，从而更全面地了解项目的所有依赖项。

依赖项关系图显示你使用 API 提交的任何依赖项，以及从存储库中的清单或锁定文件（例如 package-lock.json JavaScript 项目中的文件）标识的任何依赖项。 有关查看依赖项关系图的详细信息，请参阅 Exploring the dependencies of a repository。

提交的依赖项将收到 Dependabot alerts 和 Dependabot security updates 以处理任何已知的漏洞。 你只会收到来自 GitHub Advisory Database 支持的生态系统之一的依赖关系的 Dependabot alerts。 有关这些生态系统的详细信息，请参阅 关于 GitHub 公告数据库。 对于通过 依赖项提交 API 提交的可传递依赖项，如果更新可用，Dependabot 将自动打开拉取请求以更新父依赖项。

提交的依赖项在组织的依赖项见解中_不_可用。

Dependencies are submitted to the 依赖项提交 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 依赖项提交 API over the network, see 适用于依赖项提交的 REST API 终结点.

Submitting dependencies at build-time

You can use the 依赖项提交 API in a GitHub Actions workflow to submit dependencies for your project when your project is built.

Using pre-made actions

使用 依赖项提交 API 最简单的方法是向存储库添加预创建的操作，该操作将收集依赖项列表并将它转换为所需的快照格式，然后将此列表提交到 API。

生态系统	操作
Go	Go 依赖项提交
Gradle	Gradle 依赖项提交
Maven	Maven 依赖关系树依赖项提交
研磨	Mill 依赖项提交
Mix (Elixir)	Mix 依赖项提交
Scala	Sbt 依赖项提交
NuGet 及其他	组件检测依赖项提交操作

例如，以下 Go 依赖项提交工作流将计算 Go 生成目标（带有 main 函数的 Go 文件）的依赖项，并将列表提交到 依赖项提交 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 依赖项关系图支持的包生态系统.

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 依赖项提交 API. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in 适用于依赖项提交的 REST API 终结点.
3. Submit the formatted list of dependencies to the 依赖项提交 API.

GitHub maintains the Dependency Submission Toolkit, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the 依赖项提交 API. For more information about writing an action, see 重用自动化.

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 依赖项提交 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 依赖项提交 API.

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。
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@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/"