使用依赖项提交 API

关于依赖项提交 API

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

依赖关系图显示了您使用 API 提交的任何依赖项，以及从存储库中的清单或锁定文件中标识的任何依赖项（例如，JavaScript 项目中的 package-lock.json 文件）。有关查看依赖关系图的更多信息，请参阅“浏览存储库的依赖项”。

提交的依赖项将接收 Dependabot 警报和任何已知漏洞的 Dependabot 安全更新。您只会收到来自 GitHub 安全公告数据库支持的生态系统之一的依赖项的 Dependabot 警报。有关这些生态系统的更多信息，请参阅“关于 GitHub 安全公告数据库”。对于通过依赖项提交 API 提交的传递依赖项，如果可用更新，Dependabot 将自动打开拉取请求以更新父依赖项。

提交的依赖项将显示在依赖项审查中，但 *不* 会显示在您组织的依赖项见解中。

注意

依赖项审查 API 和依赖项提交 API 协同工作。这意味着依赖项审查 API 将包含通过依赖项提交 API 提交的依赖项。

依赖项以快照的形式提交到依赖项提交 API。快照是一组与提交 SHA 和其他元数据关联的依赖项，反映了存储库在某个提交时的当前状态。快照可以从构建时检测到的依赖项或软件物料清单 (SBOM) 生成。有一些 GitHub Actions 支持这两种用例。有关依赖项提交 API 的更多信息，请参阅“依赖项提交的 REST API 端点”。

在构建时提交依赖项

您可以在 GitHub Actions 工作流中使用依赖项提交 API，在构建项目时提交项目的依赖项。

使用预制操作

使用依赖项提交 API 的最简单方法是将预制操作添加到您的存储库中，该操作将收集并转换依赖项列表到所需的快照格式，并将列表提交到 API。

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

创建您自己的操作

或者，您可以在构建时编写自己的操作来提交项目的依赖项。您的工作流应

生成项目的依赖项列表。
将依赖项列表转换为依赖项提交 API 接受的快照格式。有关该格式的更多信息，请参阅“依赖项提交的 REST API 端点”中“创建存储库快照”API 端点的正文参数。
将格式化的依赖项列表提交到依赖项提交 API。

GitHub 维护着依赖项提交工具包，这是一个 TypeScript 库，可帮助您构建自己的 GitHub Action，用于将依赖项提交到依赖项提交 API。有关编写操作的更多信息，请参阅“共享自动化”。

生成和提交软件物料清单 (SBOM)

SBOM 是项目依赖项及其关联信息（如版本、软件包标识符、许可证和版权信息）的正式、机器可读清单。SBOM 通过以下方式帮助降低供应链风险：

提供有关存储库使用的依赖项的透明度
允许在流程早期识别漏洞
提供对代码库中可能存在的许可证合规性、安全或质量问题的见解
使您能够更好地遵守各种数据保护标准

生成软件物料清单 (SBOM)

要生成 SBOM，您可以使用

**GitHub UI**。有关如何使用依赖关系图中的信息导出存储库的 SBOM 的更多信息，请参阅“导出存储库的软件物料清单”。
**REST API**。有关更多信息，请参阅“软件物料清单 (SBOM) 的 REST API 端点”。
GitHub Actions。以下操作将为您的存储库生成 SBOM 并将其作为工作流工件附加，您可以下载这些工件并在其他应用程序中使用。有关下载工作流工件的更多信息，请参阅“下载工作流工件”。

操作	详细信息
Anchore SBOM 操作	使用 Syft 通过支持的生态系统创建与 SPDX 2.2 兼容的 SBOM。
Microsoft 的 sbom-tool	扫描您的依赖项并创建与 SPDX 兼容的 SBOM。

将软件物料清单 (SBOM) 提交到依赖项提交 API

要接收有关具有已知漏洞的依赖项的 Dependabot 警报，您可以将 SBOM 上传并提交到依赖项提交 API。要将 SBOM 提交到依赖项提交 API，您可以使用下表中列出的操作之一。

提示

SPDX 依赖项提交操作和 Anchore SBOM 操作可用于生成 SBOM 并将其提交到依赖项提交 API。

操作	详细信息
SPDX 依赖项提交操作	使用 Microsoft 的 SBOM 工具通过支持的生态系统创建与 SPDX 2.2 兼容的 SBOM。
Anchore SBOM 操作	使用 Syft 通过支持的生态系统创建与 SPDX 2.2 兼容的 SBOM。
SBOM 依赖项提交操作	将 CycloneDX SBOM 上传到依赖项提交 API。

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

本文内容