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 по всем известным уязвимостям. Вы получите только Dependabot alerts для зависимостей, которые находятся из одной из поддерживаемых экосистем для GitHub Advisory Database. Дополнительные сведения об этих экосистемах см. в разделе Сведения о базе данных GitHub Advisory. Для транзитивных зависимостей, отправленных через 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
Мельница	Отправка зависимостей Милли
Mix (Elixir)	Отправка зависимостей смешивания
Scala	Отправка зависимостей Sbt
NuGet и другие	Действие отправки зависимостей обнаружения компонентов

Например, следующий рабочий процесс отправки зависимостей Go вычисляет зависимости для целевого объекта сборки Go (файл Go с main функцией) и отправляет список в 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@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/"