Skip to main content

Configurando a ação de revisão de dependência

Você pode usar o ação de revisão de dependência para detectar vulnerabilidades antes que elas sejam adicionadas ao projeto.

Quem pode usar esse recurso?

Proprietários de repositórios, proprietários de organizações, gerentes de segurança e usuários com a função de administrador

Sobre o ação de revisão de dependência

O "ação de revisão de dependência" se refere à ação específica que pode relatar diferenças em um pull request dentro do contexto do GitHub Actions e adicionar mecanismos de imposição ao fluxo de trabalho do GitHub Actions.

O ação de revisão de dependência verifica as solicitações de pull em busca de alterações de dependência e gera um erro quando novas dependências têm vulnerabilidades conhecidas. A ação tem o suporte de um ponto de extremidade de API que compara as dependências entre duas revisões e relata as diferenças.

Para obter mais informações sobre a ação e o ponto de extremidade da API, consulte a documentação dependency-review-action e "Pontos de extremidade da API REST para revisão de dependências".

Os proprietários da organização podem implantar a revisão de dependência em escala impondo o uso do ação de revisão de dependência em repositórios da organização. Isso envolve o uso de conjuntos de regras de repositório para os quais você definirá o ação de revisão de dependência como um fluxo de trabalho obrigatório, o que significa que as pull requests só podem ser mescladas depois que o fluxo de trabalho passar por todas as verificações necessárias. Para obter mais informações, confira "Aplicando a revisão de dependência em uma organização".

Abaixo está a lista de opções de configuração comuns. Para obter mais informações e uma lista completa de opções, confira Revisão de Dependência no GitHub Marketplace.

OpçãoObrigatórioUso
fail-on-severityDefine o limite do nível de severidade (low, moderate, high e critical).
A ação falhará nas solicitações de pull que apresentarem vulnerabilidades no nível de severidade especificado ou superior.
allow-licensesContém uma lista de licenças permitidas. Veja os valores possíveis para esse parâmetro na página Licenças da documentação da API.
A ação falhará nas solicitações de pull que apresentarem dependências com licenças que não correspondam à lista.
deny-licensesContém uma lista de licenças proibidas. Veja os valores possíveis para esse parâmetro na página Licenças da documentação da API.
A ação falhará nas solicitações de pull que apresentarem dependências com licenças que correspondam à lista.
fail-on-scopesContém uma lista de cadeias de caracteres que representam os ambientes de compilação aos quais você deseja oferecer suporte (development, runtime, unknown).
A ação falhará em solicitações de pull que introduzam vulnerabilidades nos escopos que correspondem à lista.
comment-summary-in-prHabilite ou desabilite o relatório do resumo de revisão como um comentário na solicitação de pull. Se habilitado, você deve conceder a permissão pull-requests: write ao workflow ou ao trabalho.
allow-ghsasContém uma lista de IDs GitHub Advisory Database que podem ser ignorados durante a detecção. É possível encontrar os valores possíveis para este parâmetro no GitHub Advisory Database.
config-fileEspecifica um caminho para um arquivo de configuração. O arquivo de configuração pode ser local ao repositório ou pode estar em um repositório externo.
external-repo-tokenEspecifica um token para buscar o arquivo de configuração, se o arquivo residir em um repositório externo privado. O token deve ter acesso de leitura ao repositório.

Tip

As opções allow-licenses e deny-licenses são mutualmente exclusivas.

Como configurar a ação de revisão de dependência

Há dois métodos de configuração da ação de revisão de dependência:

  • Integrar as opções de configuração no arquivo de fluxo de trabalho.
  • Fazer referência a um arquivo de configuração no arquivo de fluxo de trabalho.

Observe que todos os exemplos usam um número de versão curto para a ação (v3) em vez de um número de versão semver (por exemplo, v3.0.8). Isso garante que você use a versão secundária mais recente da ação.

Usar a configuração em linha para configurar a ação de revisão de dependência

  1. Adicione um fluxo de trabalho YAML à pasta .github/workflows.

    YAML
    name: 'Dependency Review'
    on: [pull_request]
    
    permissions:
      contents: read
    
    jobs:
      dependency-review:
        runs-on: ubuntu-latest
        steps:
         - name: 'Checkout Repository'
           uses: actions/checkout@v4
         - name: Dependency Review
           uses: actions/dependency-review-action@v4
    
  2. Especifique suas configurações.

    Esse arquivo de exemplo de ação de revisão de dependência ilustra como usar as opções de configuração disponíveis.

    YAML
    name: 'Dependency Review'
    on: [pull_request]
    
    permissions:
      contents: read
    
    jobs:
      dependency-review:
        runs-on: ubuntu-latest
        steps:
        - name: 'Checkout Repository'
          uses: actions/checkout@v4
        - name: Dependency Review
          uses: actions/dependency-review-action@v4
          with:
            # Possible values: "critical", "high", "moderate", "low"
            fail-on-severity: critical
    
            
            # You can only include one of these two options: `allow-licenses` and `deny-licenses`
            # ([String]). Only allow these licenses (optional)
            # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
            allow-licenses: GPL-3.0, BSD-3-Clause, MIT
            # ([String]). Block the pull request on these licenses (optional)
            # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
            deny-licenses: LGPL-2.0, BSD-2-Clause
            
            # ([String]). Skip these GitHub Advisory Database IDs during detection (optional)
            # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories
            allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679
            # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
            # Possible values: "development", "runtime", "unknown"
            fail-on-scopes: development, runtime
    

Usar um arquivo de configuração para configurar a ação de revisão de dependência

  1. Adicione um fluxo de trabalho YAML à pasta .github/workflows e use config-file para especificar que você está usando um arquivo de configuração.

    YAML
    name: 'Dependency Review'
    on: [pull_request]
    
    permissions:
     contents: read
    
    jobs:
      dependency-review:
        runs-on: ubuntu-latest
        steps:
        - name: 'Checkout Repository'
          uses: actions/checkout@v4
        - name: Dependency Review
          uses: actions/dependency-review-action@v4
          with:
           # ([String]). Representing a path to a configuration file local to the repository or in an external repository.
           # Possible values: An absolute path to a local file or an external file.
           config-file: './.github/dependency-review-config.yml'
           # Optional alternative syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH (uncomment if preferred)
           # config-file: 'github/octorepo/dependency-review-config.yml@main'
    
           # ([Token]) Use if your configuration file resides in a private external repository.
           # Possible values: Any GitHub token with read access to the private external repository.
           external-repo-token: 'ghp_123456789abcde'
    
  2. Crie o arquivo de configuração no caminho especificado.

    Esse arquivo de exemplo YAML ilustra como é possível usar as opções de configuração disponíveis.

    YAML
      # Possible values: "critical", "high", "moderate", "low"
      fail-on-severity: critical
    
      # You can only include one of these two options: `allow-licenses` and `deny-licenses`
      # ([String]). Only allow these licenses (optional)
      # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
      allow-licenses:
        - GPL-3.0
        - BSD-3-Clause
        - MIT
       # ([String]). Block the pull request on these licenses (optional)
       # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
      deny-licenses:
        - LGPL-2.0
        - BSD-2-Clause
    
       # ([String]). Skip these GitHub Advisory Database IDs during detection (optional)
       # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories
      allow-ghsas:
        - GHSA-abcd-1234-5679
        - GHSA-efgh-1234-5679
       # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
       # Possible values: "development", "runtime", "unknown"
      fail-on-scopes:
        - development
        - runtime
    

Para saber mais detalhes sobre as opções de configuração, confira dependency-review-action.

Leitura adicional