使用依赖项提交 API

依赖项提交 API 是用于将数据提交到依赖图的方法。 它允许提交静态分析未捕获的依赖项。 有关详细信息，请参阅“依赖项图如何识别依赖项”。

在生成时提交依赖项

可以在 GitHub Actions 工作流中使用 依赖项提交 API，从而在生成项目时提交项目的依赖项。

使用预创建的操作

使用 依赖项提交 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

有关这些操作的更多信息，请参阅 依赖项关系图支持的包生态系统。

创建自己的操作

你还可以编写你自己操作，以便在生成时提交项目的依赖项。 你的工作流应：

1. 生成项目的依赖项列表。
2. 将依赖项列表转换为 依赖项提交 API 接受的快照格式。 有关格式的更多信息，请参阅 适用于依赖项提交的 REST API 终结点 中“创建存储库快照”API 终结点的请求体参数。
3. 将格式化的依赖项列表提交到 依赖项提交 API。

GitHub 维护 Dependency Submission Toolkit，这是一个 TypeScript 库，可帮助你生成自己的 GitHub Action，以便将依赖项提交到 依赖项提交 API。 有关编写操作的更多信息，请参阅 重用自动化。

将 SBOM 作为快照提交

如果有用于创建或管理软件物料清单 (SBOM) 的外部工具，也可以将这些 SBOM 提交到 依赖项提交 API。 快照数据格式与标准 SPDX 和 CycloneDX SBOM 格式非常相似，有多个工具可以生成或转换格式以用作快照。

例如，以下 SPDX 依赖项提交操作工作流将计算存储库的依赖项，生成 SPDX 2.2 格式的可导出的 SBOM，并将其提交到 依赖项提交 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/"