Fazer solicitações de API autenticadas com um Aplicativo do GitHub em um fluxo de trabalho do GitHub Actions

Sobre a autenticação do GitHub Actions

Para fazer solicitações de API autenticadas em um fluxo de trabalho do GitHub Actions ou executar uma ação personalizada que exige um token, se possível, use o GITHUB_TOKEN interno. No entanto, o GITHUB_TOKEN só pode acessar recursos dentro do repositório do fluxo de trabalho. Para acessar recursos adicionais, como recursos em uma organização ou em outro repositório, use um GitHub App. Para saber por que usar um GitHub App em vez de um personal access token, confira Sobre a criação de Aplicativos do GitHub.

Autenticação com um GitHub App

Para usar um GitHub App a fim de fazer solicitações de API autenticadas, é necessário registrar o GitHub App, armazenar as credenciais do aplicativo e instalá-lo. Feito isso, é possível usar o aplicativo a fim de criar um token de acesso de instalação que é usado para fazer solicitações de API autenticadas em um fluxo de trabalho do GitHub Actions. Também é possível transmitir o token de acesso de instalação para uma ação personalizada que requer um token.

1. Registrar o GitHub App. Dê ao registro do GitHub App as permissões necessárias para acessar os recursos desejados. Para saber mais, confira Registrar um Aplicativo GitHub e Escolhendo permissões para um Aplicativo GitHub.

2. Armazene a ID do aplicativo do GitHub App como uma variável de configuração do GitHub Actions. Para encontrar a ID do aplicativo, acesse a página de configurações dele. A ID do aplicativo é diferente da ID do cliente. Para saber como acessar a página de configurações do GitHub App, confira Modificar um registro do Aplicativo GitHub. Para obter mais informações sobre como armazenar variáveis de configuração, confira Armazenar informações em variáveis.

3. Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----.) Para saber mais, confira Como gerenciar chaves privadas para Aplicativos GitHub. Para saber mais sobre como armazenar segredos, confira Usar segredos em ações do GitHub.

4. Instale o GitHub App em sua conta de usuário ou organização e conceda a ele acesso aos repositórios que você deseja que o fluxo de trabalho acesse. Para saber mais, confira Instalando seu próprio Aplicativo GitHub.

5. No fluxo de trabalho do GitHub Actions, crie um token de acesso de instalação, que será usado para fazer solicitações de API.

   Para isso, você pode usar uma ação pertencente ao GitHub como demonstrado no exemplo a seguir. Se preferir não usar essa ação, você poderá criar fork e modificar a ação actions/create-github-app-token ou escrever um script para fazer com que o fluxo de trabalho crie um token de instalação manualmente. Para obter mais informações, confira "Como autenticar como uma instalação de Aplicativo GitHub".

   O exemplo de fluxo de trabalho a seguir usa a ação actions/create-github-app-token para gerar um token de acesso para instalação. Em seguida, o fluxo de trabalho usa o token para fazer uma solicitação de API por meio da GitHub CLI.

   No fluxo de trabalho a seguir, substitua APP_ID pelo nome da variável de configuração em que você armazenou a ID do aplicativo. Substitua APP_PRIVATE_KEY pelo nome do segredo em que você armazenou a chave privada do aplicativo.

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api octocat

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api octocat