Autenticação automática de token

Sobre o segredo _TOKEN

No início de cada trabalho do fluxo de trabalho, o cria automaticamente um segredo _TOKEN exclusivo a ser usado no seu fluxo de trabalho. Use o _TOKEN para se autenticar em um trabalho de fluxo de trabalho.

Ao habilitar Actions, instala um App no seu repositório. O segredo _TOKEN é um token de acesso de instalação do App. Você pode usar o token de acesso de instalação para autenticar em nome do App instalado no seu repositório. As permissões do token são restritas ao repositório do fluxo de trabalho. Para obter mais informações, confira Permissões para o _TOKEN.

Antes de iniciar cada trabalho, busca um token de acesso de instalação para o trabalho. O _TOKEN expira quando um trabalho é concluído ou após, no máximo, 24 horas.

O token também está disponível no contexto .token. Para saber mais, confira Acessar informações contextuais sobre execuções de fluxo de trabalho.

Como usar o _TOKEN em um fluxo de trabalho

Use o _TOKEN usando a sintaxe padrão para referenciar segredos: ${{ secrets._TOKEN }}. Exemplos de uso do _TOKEN incluem a transmissão do token como uma entrada para uma ação ou o uso dele para fazer uma solicitação de API autenticada do .

Quando você usar o _TOKEN do repositório para executar tarefas, os eventos disparados pelo _TOKEN, com exceção de workflow_dis e repository_dis, não criarão uma execução de fluxo de trabalho. Isso impede que você crie execuções de fluxo de trabalho recursivo. Por exemplo, se uma execução de fluxo de trabalho efetuar push do código usando o _TOKEN do repositório, um novo fluxo de trabalho não será executado mesmo quando o repositório contiver um fluxo de trabalho configurado para ser executado quando os eventos do push ocorrerem.

Commits enviados por push por um fluxo de trabalho de Actions que usa o _TOKEN não disparam um build de Pages.

Exemplo 1: transmissão do _TOKEN como uma entrada

Este exemplo de fluxo de trabalho usa a CLI do , que requer o _TOKEN como o valor para o parâmetro de entrada GH_TOKEN:

name: Open new issue
on: workflow_dis

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ .repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets._TOKEN }}

name: Open new issue
on: workflow_dis

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ .repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets._TOKEN }}

Exemplo 2: chamando a API REST

Use o _TOKEN para fazer chamadas à API autenticadas. Este exemplo de fluxo de trabalho cria um problema usando a API REST de :

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api..com/repos/${{ .repository }}/issues \
          --header 'authorization: Bearer ${{ secrets._TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ .sha }}",
            "body": "This issue was automatically created by the  Action workflow **${{ .workflow }}**. \n\n The commit hash was: _${{ .sha }}_."
            }' \
          --fail

Permissões para o _TOKEN

Para obter informações sobre os pontos de extremidade de API que podem ser acessados pelos Apps com cada permissão, confira Permissões necessárias para os aplicativos .

A tabela a seguir mostra as permissões concedidas para a função _TOKEN por padrão. As pessoas com permissões de administrador para uma empresa, organização ou repositório de pode definir as permissões padrão como permissivas ou restritas. Para obter informações sobre como definir as permissões padrão para o _TOKEN para sua empresa, organização ou repositório, confira Aplicando políticas para o Actions na sua empresa, Desabilitar ou limitar o Actions para sua organização ou Gerenciando as configurações do Actions para um repositório.

Como modificar as permissões para o _TOKEN

Você pode modificar as permissões para _TOKEN em arquivos de fluxo de trabalho individuais. Se as permissões padrão para o _TOKEN são restritivas, talvez seja preciso elevar as permissões para permitir que algumas ações e alguns comandos sejam executados com sucesso. Se as permissões padrão são permissivas, você pode editar o arquivo de fluxo de trabalho para remover algumas permissões do _TOKEN. Como uma boa prática de segurança, você deve conceder ao _TOKEN o acesso menos necessário.

Veja as permissões que o _TOKEN tinha Em um trabalho específico na seção "Configurar trabalho" do log de execução do fluxo de trabalho. Para saber mais, confira Usando logs de execução de fluxo de trabalho.

Use a chave permissions nos arquivos de fluxo de trabalho para modificar as permissões do _TOKEN em um fluxo de trabalho inteiro ou em trabalhos individuais. Isso permite que você configure as permissões mínimas necessárias para um fluxo de trabalho ou trabalho.

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 Actions. Para saber mais, confira Gerenciando as configurações do Actions para um repositório.

Os dois exemplos de fluxo de trabalho anteriores neste artigo mostram a chave permissions sendo usada no nível do trabalho, pois é uma prática recomendada limitar o escopo das permissões.

Para obter detalhes completos da chave permissions, confira Sintaxe de fluxo de trabalho para o Actions.

Como as permissões são calculadas para um trabalho de fluxo de trabalho

Inicialmente, as permissões para o _TOKEN são definidas como a configuração padrão para a empresa, a organização ou o repositório. Se o padrão for definido como permissões restritas em qualquer um desses níveis, isso irá aplicar-se aos repositórios relevantes. Por exemplo, Se você escolher o padrão restrito no nível da organização, todos os repositórios nessa organização usarão as permissões restritas como padrão. As permissões serão, então, ajustadas com base em qualquer configuração dentro do arquivo de fluxo de trabalho, primeiro no nível de fluxo de trabalho e, em seguida, no nível de trabalho. Por fim, se o fluxo de trabalho foi disparado por uma solicitação de pull de um repositório com fork e a configuração Enviar tokens de gravação para fluxos de trabalho por meio de solicitações de pull não está selecionada, as permissões são ajustadas para alterar as permissões de gravação para somente leitura.

Conceder permissões adicionais

Se você precisar de um token que exija permissões que não estão disponíveis no _TOKEN, crie um App e gere um token de acesso de instalação no fluxo de trabalho. Para saber mais, confira Fazer solicitações de API autenticadas com um Aplicativo do em um fluxo de trabalho do Actions. Como alternativa, é possível criar um personal access token, armazená-lo como um segredo no repositório e usar o token no fluxo de trabalho com a sintaxe ${{ secrets.SECRET_NAME }}. Para saber mais, confira Gerenciar seus tokens de acesso pessoal e Usar segredos em ações do .

Leitura adicional

• Limites de taxa para a API REST