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