Permissões mínimas para o workflow e cada trabalho

GITHUB_TOKEN permite que o GitHub Actions se autentique para realizar operações em um repositório. A chave permissions configura suas permissões para todo o workflow ou para trabalhos individuais, de modo que cada tarefa receba apenas os recursos de que precisa.

Como ponto de partida, o GitHub recomenda definir a permissão padrão de GITHUB_TOKEN como leitura do conteúdo do repositório e ampliá-la quando um trabalho específico precisar. Se um workflow apenas consulta arquivos, não precisa de permissões de escrita por conveniência.

As permissões devem corresponder à operação: criar um issue exige issues: write; outras tarefas podem precisar de permissões diferentes. Você pode definir uma base para o workflow e ajustar as permissões do trabalho que realiza a operação. Não amplie todos os trabalhos para resolver uma necessidade localizada.

As actions também podem acessar o token pelo contexto github.token, mesmo que ele não seja passado como entrada. Por isso, limite as permissões e revise quais actions são executadas em cada trabalho. Não passar secrets.GITHUB_TOKEN explicitamente não prova que uma action não tenha acesso ao token.

Exemplo de workflow somente leitura

O modelo a seguir é acionado por alterações em main e concede leitura do conteúdo do repositório. Antes de usá-lo, substitua actions/checkout@<SHA_COMPLETO_VERIFICADO> por um SHA completo real e verificado; o marcador não é uma referência executável.

Modelo adaptável: substitua o marcador por um SHA completo verificado antes de salvar e executar o workflow.

name: Verificar alterações

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verificar:
    runs-on: ubuntu-latest
    steps:
      - name: Obter o código
        uses: actions/checkout@<SHA_COMPLETO_VERIFICADO>

      - name: Executar verificações
        run: ./scripts/check.sh

Fixar uma action em um SHA completo reduz o risco de uma tag mudar de destino, mas não comprova que o código seja seguro. Verifique se o SHA pertence ao repositório esperado e revise o código das actions utilizadas. O GitHub apresenta arquivos de bloqueio de dependências como uma proteção mais robusta do que fixar SHAs isoladamente.

Ajuste as permissões ao trabalho real. Se não precisar consultar o repositório, avalie se contents: read é necessário. Se adicionar uma operação de escrita, identifique a permissão necessária e conceda-a ao trabalho correspondente, em vez de ampliar o acesso de todo o workflow.

Conceder escrita somente ao trabalho que precisa dela

Para criar um issue com o GitHub CLI, um trabalho precisa da permissão issues: write. O exemplo documentado pelo GitHub configura essa permissão no trabalho e fornece o token à ferramenta por meio da variável de ambiente GH_TOKEN.

name: Criar issue

on:
  workflow_dispatch:

jobs:
  criar-issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Criar issue com o GitHub CLI
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh issue create --title "Tarefa automatizada" --body "Revise o resultado do workflow."

Não grave segredos diretamente nos arquivos do workflow nem os imprima nos registros. O GitHub alerta que o mascaramento automático não é garantido para valores transformados. Se uma credencial aparecer desprotegida em um registro, exclua o registro afetado e altere a credencial.

Se GITHUB_TOKEN não oferecer as permissões necessárias, o GitHub documenta alternativas: um token de instalação de um GitHub App ou um token de acesso pessoal armazenado como segredo. Aplique o princípio do menor privilégio e limite quem pode acessar essas credenciais.

Pull requests externos e tarefas privilegiadas

O conteúdo de uma pull request externa deve ser tratado como entrada não confiável: quem a envia pode controlar o código, os scripts e as dependências executados durante os testes. O GitHub Security Lab informa que, por padrão, o evento pull_request impede permissões de escrita e acesso aos segredos do repositório de destino para solicitações provenientes de forks.

pull_request_target é executado no contexto do repositório de destino e pode ter permissões de escrita e acesso a segredos. O risco surge quando esse contexto privilegiado é combinado com a obtenção e a execução de código externo: scripts, testes e instalações de pacotes controlados por quem envia a PR podem executar código no ambiente do workflow.

Não execute código não confiável em um trabalho privilegiado. pull_request_target pode ser usado em tarefas limitadas, como adicionar etiquetas ou comentários, se o workflow não executar código controlado pela pull request. Um checkout explícito, por si só, não prova que houve exploração: o conteúdo também pode ser tratado como dado passivo, mas não deve controlar processos de compilação, teste ou instalação.

Para testar código externo, use um workflow não privilegiado com pull_request. Se depois precisar publicar um resultado com permissões de escrita, você pode separar os testes dessa tarefa usando workflow_run. Artefatos produzidos a partir da pull request continuam sendo dados não confiáveis: o workflow privilegiado pode ler as informações necessárias, mas não deve executar binários nem scripts provenientes desses artefatos.

Revise também as pull requests que já estavam abertas quando você alterou um workflow vulnerável. O GitHub Security Lab alerta que uma solicitação pendente pode continuar usando a versão do workflow existente quando foi aberta; talvez seja necessário fechá-la ou atualizá-la de forma controlada.

Pull requests externos y tareas privilegiadas El contenido de un pull request externo debe tratarse como entrada no confiable: quien lo presenta puede controlar código, scripts y d...
Ilustração editorial do BytePreview

Entradas, actions e segredos

Dados de uma pull request podem chegar ao shell por meio de expressões do workflow. Para reduzir o risco de injeção, o GitHub recomenda guardar o valor externo em uma variável de ambiente intermediária e usar essa variável no script, em vez de interpolar os dados diretamente no comando.

As actions de terceiros também precisam ser revisadas. Os trabalhos podem compartilhar informações ou recursos, e uma action comprometida pode afetar o token e os segredos disponíveis. Revise o código de cada action e confira se ela não envia segredos a destinos inesperados nem os grava nos registros.

Para workflows que acessam serviços de nuvem compatíveis, o GitHub recomenda considerar a autenticação OIDC em vez de armazenar credenciais de longa duração como segredos. Se um trabalho precisar de segredos de um ambiente, você pode configurar revisores obrigatórios para que o acesso dependa de uma aprovação.

Reduza os segredos disponíveis ao mínimo indispensável e audite seu uso. O mascaramento dos registros ajuda, mas não substitui a separação entre código confiável e não confiável; altere as credenciais se forem expostas.

Lista de verificação para um workflow existente

Comece identificando o evento que aciona cada trabalho e siga o caminho até suas permissões, actions, segredos e dados de entrada. Não procure apenas secrets.GITHUB_TOKEN: uma action pode acessar o token por meio de github.token.

  • O trabalho pode funcionar com leitura em vez de escrita?
  • A permissão de escrita está limitada ao trabalho que realiza essa operação?
  • Um workflow privilegiado processa código ou artefatos de uma pull request externa?
  • As actions estão fixadas em SHAs completos verificados e seu código é revisado?
  • Valores externos chegam ao shell por meio de variáveis de ambiente intermediárias?
  • Os segredos são indispensáveis e sua exposição nos registros é evitada?

Em repositórios públicos, dê atenção especial aos runners auto-hospedados. O GitHub alerta que código não confiável pode comprometê-los de forma persistente. Em contrapartida, descreve seus runners hospedados como máquinas virtuais limpas e efêmeras; essa descrição não é uma garantia para runners auto-hospedados e não elimina a necessidade de limitar permissões e segredos.

Como regra operacional, combine leitura por padrão, escrita quando necessária e isolamento do código externo. Depois de testar um workflow, revise os registros para verificar se informações confidenciais foram expostas e altere qualquer credencial comprometida.