Skip to main content

使用依赖项提交 API

可以使用依赖项提交 API 来提交项目的依赖项,例如生成或编译项目时解析的依赖项。

注意:使用 REST API 进行依赖项提交的功能目前为公共 beta 版本,可能会发生更改。

关于依赖项提交 API

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

依赖项关系图显示你使用 API 提交的任何依赖项,以及从存储库中的清单或锁定文件(例如 package-lock.json JavaScript 项目中的文件)标识的任何依赖项。 有关查看依赖项关系图的详细信息,请参阅“探索仓库的依赖项”。

提交的依赖项将收到 Dependabot alerts 和 Dependabot security updates 以处理任何已知的漏洞。 你只会收到来自 GitHub Advisory Database 支持的生态系统之一的依赖关系的 Dependabot alerts。 有关这些生态系统的详细信息,请参阅“关于 GitHub 公告数据库”。 提交的依赖关系将会显示在依赖关系审查或组织的依赖关系见解中。

注意: 依赖关系审查 API 和依赖关系提交 API 协同工作。 这意味着依赖关系审查 API 将包括通过依赖关系提交 API 提交的依赖关系。 此功能目前为公共 beta 版本,可能会有变动。

__

依赖项以快照的形式提交到依赖项提交 API。 快照是一组与提交 SHA 和其他元数据关联的依赖项,反映提交存储库的当前状态。 可根据生成时检测到的依赖项或软件物料清单 (SBOM) 生成快照。 有 GitHub Actions 支持上述任一用例。 有关依赖项提交 API 的详细信息,请参阅依赖项提交 REST API 文档

在生成时提交依赖项

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

使用预创建的操作

使用依赖项提交 API 最简单的方法是向存储库添加预创建的操作,该操作将收集依赖项列表并将它转换为所需的快照格式,然后将此列表提交到 API。 GitHub Marketplace 上提供了针对各种生态系统完成这些步骤的操作。 其中一些操作由第三方提供。 可以在下表中找到当前可用操作的链接。

生态系统操作由 GitHub 维护
GoGo 依赖项提交
GradleGradle 依赖项提交
MavenMaven 依赖关系树依赖项提交
研磨Mill 依赖项提交
ScalaSbt 依赖项提交

例如,以下 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@v4

      - uses: actions/setup-go@v4
        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

创建自己的操作

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

  1. 生成项目的依赖项列表。
  2. 将依赖项列表转换为依赖项提交 API 接受的快照格式。 有关格式的详细信息,请参阅依赖项提交 REST API 文档中“创建存储库快照”API 操作的正文参数。
  3. 将格式化的依赖项列表提交到依赖项提交 API。

GitHub 将维护依赖项提交工具包,这是一个 TypeScript 库,可帮助你生成自己的 GitHub 操作,用于将依赖项提交到依赖项提交 API。 有关编写操作的详细信息,请参阅“创建操作”。

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

SBOM 是一份计算机可读的正式清单,其中包含项目的依赖项和相关信息(例如版本、包标识符和许可证)。 SBOM 通过以下方式帮助降低供应链风险:

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

要生成 SBOM,可以使用:

  • GitHub 用户界面。 若要详细了解如何使用依赖项关系图中的信息导出存储库的 SBOM,请参阅“导出存储库的软件物料清单”。
  • REST API。 有关详细信息,请参阅“软件材料清单 (SBOM)”。
  • GitHub Actions。 以下操作将为存储库生成 SBOM,并将其附加为工作流项目 - 你可下载该项目并在其他应用程序中使用。 若要详细了解如何下载工作流项目,请参阅“下载工作流程构件”。
操作详细信息由 GitHub 维护
SBOM-generator-action使用依赖项关系图中的信息生成 SPDX SBOM
Anchore SBOM 操作使用 Syft 通过受支持的生态系统创建与 SPDX 2.2 兼容的 SBOM
Microsoft 提供的 sbom-tool扫描依赖项并创建与 SPDX 兼容的 SBOM

然后,可执行以下操作之一来将 SBOM 上传并提交到依赖项提交 API,以便可接收具有已知漏洞的任何依赖项的 Dependabot alerts。 可将两个表中都显示的操作配置为生成和提交 SBOM。

操作详细信息由 GitHub 维护
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@v3
      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/"