Observação: no momento, não há suporte para os executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.
Sobre o segredo GITHUB_TOKEN
No início de cada trabalho do fluxo de trabalho, o GitHub cria automaticamente um segredo GITHUB_TOKEN
exclusivo a ser usado no seu fluxo de trabalho. Use o GITHUB_TOKEN
para se autenticar em um trabalho de fluxo de trabalho.
Ao habilitar GitHub Actions, GitHub instala um GitHub App no seu repositório. O segredo GITHUB_TOKEN
é um token de acesso de instalação do GitHub App. Você pode usar o token de acesso de instalação para autenticar em nome do GitHub 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 GITHUB_TOKEN
".
Antes de iniciar cada trabalho, GitHub busca um token de acesso de instalação para o trabalho. O GITHUB_TOKEN
expira quando um trabalho é concluído ou após, no máximo, 24 horas.
O token também está disponível no contexto github.token
. Para obter mais informações, confira "Accessing contextual information about workflow runs".
Como usar o GITHUB_TOKEN
em um fluxo de trabalho
Use o GITHUB_TOKEN
usando a sintaxe padrão para referenciar segredos: ${{ secrets.GITHUB_TOKEN }}
. Entre os exemplos de uso do token GITHUB_TOKEN
estão 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 GitHub Enterprise Server.
Importante: uma ação pode acessar o GITHUB_TOKEN
por meio do contexto github.token
, mesmo que o fluxo de trabalho não transmita GITHUB_TOKEN
explicitamente para a ação. Como uma boa prática de segurança, você deve sempre garantir que as ações tenham apenas o acesso mínimo necessário limitando as permissões concedidas ao GITHUB_TOKEN
. Para obter mais informações, confira "Permissões para o GITHUB_TOKEN
".
Quando você usar o GITHUB_TOKEN
do repositório para executar tarefas, eventos disparados pelo GITHUB_TOKEN
, com exceção do workflow_dispatch
e do repository_dispatch
, 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 GITHUB_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 GitHub Actions que usa o GITHUB_TOKEN
não disparam um build de GitHub Pages.
Exemplo 1: transmissão do GITHUB_TOKEN
como uma entrada
Este exemplo de fluxo de trabalho usa a CLI do GitHub, que requer o GITHUB_TOKEN
como o valor para o parâmetro de entrada GH_TOKEN
:
name: Open new issue on: workflow_dispatch jobs: open-issue: runs-on: ubuntu-latest permissions: contents: read issues: write steps: - run: | gh issue --repo ${{ github.repository }} \ create --title "Issue title" --body "Issue body" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
name: Open new issue
on: workflow_dispatch
jobs:
open-issue:
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
steps:
- run: |
gh issue --repo ${{ github.repository }} \
create --title "Issue title" --body "Issue body"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Exemplo 2: chamando a API REST
Use o GITHUB_TOKEN
para fazer chamadas à API autenticadas. Este exemplo de fluxo de trabalho cria um problema usando a API REST de GitHub:
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 http(s)://HOSTNAME/api/v3/repos/${{ github.repository }}/issues \
--header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
--header 'content-type: application/json' \
--data '{
"title": "Automated issue for commit: ${{ github.sha }}",
"body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
}' \
--fail
Permissões para o GITHUB_TOKEN
Para obter informações sobre os pontos de extremidade de API que podem ser acessados pelos GitHub Apps com cada permissão, confira "Permissões necessárias para os aplicativos GitHub".
A tabela a seguir mostra as permissões concedidas para a função GITHUB_TOKEN
por padrão. As pessoas com permissões de administrador para uma empresa, organização ou repositório de organização ou repositório 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 GITHUB_TOKEN
para sua empresa, organização ou repositório, confira "Aplicando políticas para o GitHub Actions na sua empresa", "Desabilitar ou limitar o GitHub Actions para sua organização" ou "Gerenciando as configurações do GitHub Actions para um repositório".
Escopo | Acesso padrão (permissivo) | Acesso padrão (restrito) | Acesso máximo a solicitações de pull de repositórios públicos com fork |
---|---|---|---|
Ações | leitura/gravação | nenhum | leitura |
verificações | leitura/gravação | nenhum | leitura |
conteúdos | leitura/gravação | leitura | leitura |
deployments | leitura/gravação | nenhum | leitura |
discussões | leitura/gravação | nenhum | leitura |
issues | leitura/gravação | nenhum | leitura |
metadata | leitura | leitura | leitura |
pacotes | leitura/gravação | leitura | leitura |
páginas | leitura/gravação | nenhum | leitura |
pull-requests | leitura/gravação | nenhum | leitura |
repository-projects | leitura/gravação | nenhum | leitura |
security-events | leitura/gravação | nenhum | leitura |
status | leitura/gravação | nenhum | leitura |
Observações:
- Quando um fluxo de trabalho é disparado pelo evento
pull_request_target
, recebe permissãoGITHUB_TOKEN
de repositório de leitura/gravação, mesmo quando é disparado de uma bifurcação pública. Para obter mais informações, confira "Eventos que disparam fluxos de trabalho". - Os repositórios privados podem controlar se as solicitações de pull provenientes de forks podem executar fluxos de trabalho e configurar as permissões atribuídas a
GITHUB_TOKEN
. Para obter mais informações, confira "Gerenciando as configurações do GitHub Actions para um repositório". - As execuções de fluxo de trabalho disparadas pelas solicitações de pull do Dependabot são executadas como se fossem de um repositório com fork e, portanto, usam um
GITHUB_TOKEN
somente leitura. Estas execuções de fluxo de trabalho não podem acessar nenhum segredo. Para obter mais informações sobre as estratégias para manter esses fluxos de trabalho seguros, confira "Fortalecimento de segurança para o GitHub Actions."
Como modificar as permissões para o GITHUB_TOKEN
Você pode modificar as permissões para GITHUB_TOKEN
em arquivos de fluxo de trabalho individuais. Se as permissões padrão para o GITHUB_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 GITHUB_TOKEN
. Como uma boa prática de segurança, você deve conceder ao GITHUB_TOKEN
o acesso menos necessário.
Veja as permissões que o GITHUB_TOKEN
tinha Em um trabalho específico na seção "Configurar trabalho" do log de execução do fluxo de trabalho. Para obter mais informações, 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 GITHUB_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. Quando a chave permissions
é usada, todas as permissões não especificadas são definidas como sem acesso, com exceção do escopo metadata
, que sempre obtém acesso de leitura.
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".
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 GitHub Actions".
Nota: os proprietários da organização e da empresa podem impedir que você conceda acesso de gravação ao GITHUB_TOKEN
no nível do repositório. Para obter mais informações, confira "Desabilitar ou limitar o GitHub Actions para sua organização.e "Aplicando políticas para o GitHub Actions na sua empresa".
Como as permissões são calculadas para um trabalho de fluxo de trabalho
Inicialmente, as permissões para o GITHUB_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 GITHUB_TOKEN
, crie um GitHub App e gere um token de acesso de instalação no fluxo de trabalho. Para obter mais informações, confira "Fazer solicitações de API autenticadas com um Aplicativo do GitHub em um fluxo de trabalho do GitHub 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 obter mais informações, confira "Gerenciar seus tokens de acesso pessoal" e "Usar segredos em ações do GitHub."