Como usar a API de envio de dependência

Observação: a capacidade de usar a API REST para envio de dependência está atualmente em versão beta pública e sujeita a alterações.

Sobre a API de envio de Dependência

Você pode usar a API REST para enviar dependências para um projeto. Isso permite que você adicione dependências, como aquelas resolvidas quando o software é compilado ou criado, ao recurso de gráfico de dependências do GitHub, fornecendo uma visão mais completa de todas as dependências do seu projeto.

O gráfico mostra todas as dependências que você envia usando a API, além de quaisquer dependências identificadas por meio de arquivos de manifesto ou de bloqueio no repositório (por exemplo, um arquivo package-lock.json em um projeto JavaScript). Para obter mais informações sobre exibição do grafo de dependência, confira "Explorar as dependências de um repositório".

As dependências enviadas receberão Dependabot alerts e Dependabot security updates para quaisquer vulnerabilidades conhecidas. Você só obterá Dependabot alerts para dependências que são de um dos ecossistemas com suporte do GitHub Advisory Database. As dependências enviadas não serão exibidas na revisão de dependência ou nas informações de dependência da sua organização.

As dependências são enviadas à API Envio de dependência em forma de instantâneo. Um instantâneo é um conjunto de dependências associadas a um SHA de commit e a outros metadados, que reflete o estado atual do repositório de um commit. Instantâneos podem ser gerados por meio de suas dependências detectadas no momento da compilação ou de uma SBOM (lista de materiais de software). Há GitHub Actions que dão suporte a qualquer um desses casos de uso. Para ver mais informações sobre a API de envio de dependência, confira a Documentação da API REST de envio de dependência.

Como enviar dependências em tempo de build

Você pode usar a API de envio de dependência em um fluxo de trabalho GitHub Actions para enviar dependências para seu projeto quando ele é criado.

Usando ações pré-fabricadas

A maneira mais simples de usar a API de envio de dependência é adicionando uma ação pré-criada ao 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. As ações para realizar essas etapas em diversos ecossistemas estão disponíveis em GitHub Marketplace. Algumas dessas ações são fornecidas por terceiros. Veja os links para as ações atualmente disponíveis na tabela abaixo.

Ecossistema	Ação	Mantido por GitHub
Go	Envio de Dependência Go
Gradle	Gradle Dependency Submission
Maven	Maven Dependency Tree Dependency Submission
Mill	Mill Dependency Submission
Scala	Sbt Dependency Submission

Por exemplo, o fluxo de trabalho de Envio de Dependência Go a seguir calcula as dependências para um destino de build Go (um arquivo Go com uma função main) e envia a lista para a 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

# Envionment 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@v3

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

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:

Gere uma lista de dependências para seu projeto.
Traduza a lista de dependências para o formato de instantâneo aceito pela API de envio de dependência. Para obter mais informações sobre o formato, consulte os parâmetros do corpo da operação da API "Criar um instantâneo do repositório" na Documentação da API REST de envio de dependência.
Envie a lista formatada de dependências para a API de envio de dependência.

GitHub Enterprise Server mantém o Kit de ferramentas de envio de dependência, uma biblioteca TypeScript para ajudar você a criar sua própria ação do GitHub para enviar dependências à API de envio de dependências. Para obter mais informações sobre como escrever uma ação, confira "Criar ações".

Como gerar e enviar uma SBOM (lista de materiais de software)

Você pode usar GitHub Actions para gerar uma SBOM (lista de materiais de software), um inventário formal e legível por computador das suas dependências e informações associadas. As ações a seguir vão gerar uma SBOM para seu repositório e o anexarão como um artefato de fluxo de trabalho que você pode baixar e usar em outros aplicativos. Para obter mais informações sobre como baixar artefatos de fluxo de trabalho, confira "Fazer o download de artefatos do fluxo de trabalho".

Ação	Detalhes	Mantido por GitHub
SBOM-generator-action	Usa as informações no grafo de dependência para gerar uma SBOM do SPDX
Anchore SBOM Action	Usa o Syft para criar SBOMs compatíveis com SPDX 2.2 com os ecossistemas com suporte
Ferramenta de SBOM da Microsoft	Examina suas dependências e cria uma SBOM compatível com SPDX

Em seguida, você pode carregar e enviar a SBOM para a API de envio de dependência usando uma das ações a seguir para que possa receber Dependabot alerts em quaisquer dependências que tenham vulnerabilidades conhecidas. As ações que aparecem em ambas as tabelas podem ser configuradas para gerar e enviar uma SBOM.

Ação	Detalhes	Mantido por GitHub
Ação de Envio de Dependência do SPDX	Usa a Ferramenta de SBOM da Microsoft para criar SBOMs compatíveis com SPDX 2.2 com os ecossistemas com suporte
Anchore SBOM Action	Usa o Syft para criar SBOMs compatíveis com SPDX 2.2 com os ecossistemas com suporte
Ação de Envio de Dependência de SBOM	Carrega uma SBOM do CycloneDX para a API de envio de dependência

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


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@v3
    - 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/"