Использование API отправки зависимостей

О API отправки зависимостей

Rest API можно использовать для отправки зависимостей для проекта. Так вы сможете добавлять зависимости, например разрешаемые при компиляции или сборке программного обеспечения, в функцию графа зависимостей GitHub, чтобы создать более полную картину всех зависимостей проекта.

На графе зависимостей отображаются все зависимости, которые вы отправили через этот API, а также те, которые определены в файлах манифеста или блокировки, размещенных в репозитории (например, файл package-lock.json в проекте JavaScript). Дополнительные сведения о просмотре граф зависимостей см. в разделе Изучение зависимостей репозитория.

Отправленные зависимости будут получать Dependabot alerts и Dependabot security updates по всем известным уязвимостям. Вы получите только Dependabot alerts для зависимостей, которые находятся из одной из поддерживаемых экосистем для GitHub Advisory Database. Дополнительные сведения об этих экосистемах см. в разделе Сведения о базе данных GitHub Advisory. Для транзитивных зависимостей, отправленных через API отправки зависимостей, Dependabot автоматически открывает запросы на вытягивание для обновления родительской зависимости, если обновление доступно.

Отправленные зависимости будут отображаться в проверке зависимостей, но недоступны в аналитике зависимостей вашей организации.

Примечание.

API проверки зависимостей и API отправки зависимостей работают вместе. Это означает, что API проверки зависимостей будет включать зависимости, отправленные через API отправки зависимостей.

Зависимости отправляются в API отправки зависимостей в виде моментального снимка. Моментальный снимок — это набор зависимостей, связанных с SHA фиксации и другими метаданными, которые отражают текущее состояние репозитория для фиксации. Моментальные снимки можно создать из зависимостей, обнаруженных во время сборки. Технические сведения об использовании API отправки зависимостей в сети см. в разделе Конечные точки REST API для отправки зависимостей.

Отправка зависимостей во время сборки

Вы можете использовать API отправки зависимостей в рабочем процессе GitHub Actions для отправки зависимостей для проекта при создании проекта.

Использование готовых действий

Самый простой способ использования API отправки зависимостей заключается в добавлении предварительно созданного действия в репозиторий, которое собирает и преобразует список зависимостей в требуемый формат моментального снимка и отправляет список в API.

Экосистема	Действие
Go	Отправка зависимостей Go
Gradle	Отправка зависимостей Gradle
Maven	Отправка зависимостей дерева зависимостей Maven
Мельница	Отправка зависимостей Милли
Mix (Elixir)	Отправка зависимостей смешивания
Scala	Отправка зависимостей Sbt
NuGet и другие	Действие отправки зависимостей обнаружения компонентов

Примечание.

Для действия отправки зависимостей обнаружения компонентов другие поддерживаемые экосистемы включают Vcpkg, Conan, Conda, Crates, а также 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@v4

      - 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

Дополнительные сведения об этих действиях см. в разделе Поддерживаемые экосистемы пакетов графа зависимостей.

Создание собственного действия

Кроме того, можно написать собственное действие для отправки зависимостей для проекта во время сборки. Рабочий процесс должен делать следующее:

Создать список зависимостей для проекта.
Преобразуйте список зависимостей в формат моментального снимка, принятый API отправки зависимостей. Дополнительные сведения о формате см. в параметрах текста конечной точки API "Создание моментального снимка репозитория" в Конечные точки REST API для отправки зависимостей.
Отправьте форматированный список зависимостей в API отправки зависимостей.

GitHub поддерживает набор средств отправки зависимостей, библиотеку TypeScript, помогающую создавать собственные действия GitHub для отправки зависимостей в API отправки зависимостей. Дополнительные сведения о написании действия см. в разделе Повторное выполнение автоматизации.

Отправка SBOM в виде моментальных снимков

Если у вас есть внешние средства, которые создают или управляют счетами по программному обеспечению материалов (SBOMs), вы также можете отправить эти SBOM в API отправки зависимостей. Формат данных моментальных снимков очень похож на стандартные форматы SPDX и циклонеDX SBOM, и есть несколько средств, которые могут создавать или преобразовывать форматы для использования в качестве моментальных снимков.

Совет

Действие отправки зависимостей SPDX и действие привязки SBOM можно использовать для создания SBOM и отправки его в API отправки зависимостей.

Например, следующий рабочий процесс действия отправки зависимостей SPDX вычисляет зависимости для репозитория, создает экспортируемый SBOM в формате SPDX 2.2 и отправляет его в 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/"