Controlando permissões para GITHUB_TOKEN

Visão geral

Use permissions para modificar as permissões padrão concedidas ao GITHUB_TOKEN, adicionando ou removendo o acesso conforme necessário, de modo que você só permita o acesso mínimo necessário. Para obter mais informações, confira "Autenticação automática de token".

Use permissions como uma chave de nível superior a ser aplicada a todos os trabalhos no fluxo de trabalho ou em trabalhos específicos. Quando você adiciona a chave permissions a um trabalho específico, todas as ações e os comandos de execução nesse trabalho que usam o GITHUB_TOKEN obtêm os direitos de acesso especificados. Para obter mais informações, confira jobs.<job_id>.permissions.

Para cada uma das permissões disponíveis mostradas na tabela abaixo, você pode atribuir um dos níveis de acesso: read (se aplicável), write ou none. O write inclui read. Se você especificar o acesso para uma dessas permissões, todas aquelas que não forem especificadas serão definidas como none.

Permissões disponíveis e detalhes do que cada um permite que uma ação faça:

Permissão	Permite uma ação que usa GITHUB_TOKEN para
actions	Trabalhar com GitHub Actions. Por exemplo, actions: write permite que uma ação cancele uma execução de fluxo de trabalho. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
checks	Trabalhar com verificação de execuções e verificação de conjuntos. Por exemplo, checks: write permite que uma ação crie uma verificação de execução. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
contents	Trabalhar com o conteúdo do repositório. Por exemplo, contents: read permite que uma ação liste os commits e contents: write permite que a ação crie uma versão. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
deployments	Trabalhar com implantações. Por exemplo, deployments: write permite que uma ação crie uma implantação. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
discussions	Trabalhar com o GitHub Discussions. Por exemplo, discussions: write permite que uma ação feche ou exclua uma discussão. Para obter mais informações, consulte "Usar a API do GraphQL para discussões".
issues	Trabalhar com problemas. Por exemplo, issues: write permite que uma ação adicione um comentário a um problema. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
packages	Trabalhar com GitHub Packages. Por exemplo, packages: write permite que uma ação carregue e publique pacotes no GitHub Packages. Para obter mais informações, consulte "Sobre permissões para o GitHub Packages".
pages	Trabalhar com GitHub Pages. Por exemplo, pages: write permite que uma ação solicite um build de GitHub Pages. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
pull-requests	Trabalhar com solicitações pull. Por exemplo, pull-requests: write permite que uma ação adicione um rótulo a uma PR. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
repository-projects	Trabalhar com projetos do GitHub (clássico). Por exemplo, repository-projects: write permite que uma ação adicione uma coluna a um projeto (clássico). Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".
security-events	Trabalhar com a verificação de código do GitHub e os alertas do Dependabot. Por exemplo, security-events: read permite que uma ação liste os alertas do Dependabot para o repositório e security-events: write permite que uma ação atualize o status de um alerta de verificação de código. Para obter mais informações, consulte "Permissões de repositório para "Alertas de verificação de código"" e "Permissões de repositório para "alertas do Dependabot"" em "Permissões necessárias para aplicativos do GitHub".
statuses	Trabalhar com status de commits. Por exemplo, statuses:read permite que uma ação liste os status de commit de uma determinada referência. Para obter mais informações, consulte "Permissões necessárias para os aplicativos GitHub".

Definindo o acesso para as permissões de GITHUB_TOKEN

Você pode definir o acesso que o GITHUB_TOKEN permitirá especificando read, write ou none como o valor das permissões disponíveis na chave permissions.

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Se você especificar o acesso para uma dessas permissões, todas aquelas que não forem especificadas serão definidas como none.

Você pode usar a sintaxe a seguir para definir o acesso de read-all ou write-all para todas as permissões disponíveis:

permissions: read-all

permissions: write-all

Você pode usar a seguinte sintaxe para desabilitar as permissões para todas as permissões disponíveis:

permissions: {}

Alterar as permissões em um repositório bifurcado

Além disso, você pode usar a chave permissions para adicionar e remover permissões de leitura para repositórios com fork, mas normalmente não pode permitir acesso de gravação. A exceção desse comportamento é quando um usuário administrador selecionou a opção Enviar tokens para fluxos de trabalho de solicitações de pull nas configurações do GitHub Actions. Para obter mais informações, confira "Gerenciando as configurações do GitHub Actions para um repositório".

Definir as permissões do GITHUB_TOKEN para todos os trabalhos em um fluxo de trabalho

Você pode especificar permissions no nível superior de um fluxo de trabalho para que a configuração se aplique a todos os trabalhos no fluxo de trabalho.

Exemplo: definir as permissões do GITHUB_TOKEN para um fluxo de trabalho inteiro

Este exemplo mostra as permissões que estão sendo definidas para o GITHUB_TOKEN que se aplicará a todos os trabalhos no fluxo de trabalho. É concedido acesso de leitura a todas as permissões.

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

Definir as permissões GITHUB_TOKEN para um trabalho específico

Para um trabalho específico, você pode usar jobs.<job_id>.permissions para modificar as permissões padrão concedidas ao GITHUB_TOKEN, adicionando ou removendo o acesso conforme necessário, para que você permita apenas o acesso mínimo necessário. Para obter mais informações, confira "Autenticação automática de token".

Ao especificar a permissão em uma definição de trabalho, você pode configurar um conjunto diferente de permissões para o GITHUB_TOKEN em cada trabalho, se necessário. Como alternativa, você pode especificar as permissões para todas as tarefas do fluxo de trabalho. Para obter informações sobre como definir permissões no nível do fluxo de trabalho, confira permissions.

Exemplo: definir as permissões do GITHUB_TOKEN para um trabalho em um fluxo de trabalho

Este exemplo mostra as permissões que estão sendo definidas para o GITHUB_TOKEN que se aplicará somente ao trabalho chamado stale. O acesso de gravação é permitido para as permissões issues e pull-requests. Nenhuma outra permissão terá acesso.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5