Usar a API de envio de dependências

O API de envio de dependência é um método para enviar dados para o grafo de dependência. Ele permite que você envie dependências que não são capturadas pela análise estática. Para obter mais informações, consulte Como o grafo de dependência reconhece dependências.

Como enviar dependências em tempo de build

Você pode usar o API de envio de dependência em um fluxo de trabalho GitHub Actions para enviar as dependências do seu projeto quando ele for compilado.

Usando ações pré-fabricadas

A maneira mais simples de usar API de envio de dependência é adicionar uma ação predefinida a seu repositório que reunirá e converterá a lista de dependências para o formato de instantâneo necessário e enviará a lista para a API.

Ecossistema	Ação
Go	Envio de Dependência Go
Gradle	Gradle Dependency Submission
Maven	Maven Dependency Tree Dependency Submission
Mill	Mill Dependency Submission
Mix (Elixir)	Envio de Dependência Mix
Scala	Sbt Dependency Submission
NuGet e outros	Ação de envio de dependência de detecção de componente

Por exemplo, o fluxo de trabalho de Envio de Dependência Go a seguir calcula as dependências para um destino de compilação Go (um arquivo Go com uma função main) e envia a lista para API de envio de dependência.

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@v6

      - 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

Para obter mais informações sobre essas ações, consulte Ecossistemas de pacotes com suporte a gráficos de dependência.

Como criar sua própria ação

Como alternativa, você pode escrever sua própria ação para enviar dependências para seu projeto em tempo de compilação. Seu fluxo de trabalho deve:

1. Gere uma lista de dependências para seu projeto.
2. Traduza a lista de dependências para o formato de snapshot aceito pelo API de envio de dependência. Para obter mais informações sobre o formato, consulte os parâmetros do corpo do ponto de extremidade de API "Criar um instantâneo do repositório" em Pontos de extremidade da API REST para envio de dependências.
3. Envie a lista formatada de dependências para o API de envio de dependência.

GitHub mantém o Dependency Submission Toolkit, uma biblioteca TypeScript para ajudá-lo a criar sua própria Ação GitHub para enviar dependências ao API de envio de dependência. Para obter mais informações sobre como escrever uma ação, consulte Reutilização de automações.

Enviar SBOMs como instantâneos

Se você tiver ferramentas externas que criam ou gerenciam SBOMs (listas de materiais de software), também poderá enviar esses SBOMs para o API de envio de dependência. O formato de dados do instantâneo é muito semelhante aos formatos de SBOM SPDX e CycloneDX padrão e há várias ferramentas que podem gerar ou traduzir formatos para uso como instantâneos.

Por exemplo, o fluxo de trabalho Ação de Envio de Dependências SPDX a seguir calcula as dependências de um repositório, gera um SBOM exportável no formato SPDX 2.2 e o submete ao API de envio de dependência.

# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.
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@v6
    - 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/"