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

Sobre autenticação GitHub Actions

Se você precisar fazer solicitações autenticadas à API em um fluxo de trabalho GitHub Actions ou precisar executar uma ação personalizada que exija um token, use o GITHUB_TOKEN integrado, se possível. No entanto, o GITHUB_TOKEN só pode acessar recursos dentro do repositório do fluxo de trabalho. Se você precisar acessar recursos adicionais, como recursos em uma organização ou em outro repositório, poderá usar um GitHub App. Para obter mais informações sobre por que você pode usar um GitHub App sobre um personal access token, consulte Sobre a criação de aplicativos GitHub.

Autenticando com um GitHub App

Para usar um GitHub App para fazer solicitações de API autenticadas, você deve registrar um GitHub App, armazenar as credenciais do aplicativo e instalar seu aplicativo. Depois que isso for feito, você poderá usar seu aplicativo para criar um token de acesso de instalação, que pode ser usado para fazer solicitações de API autenticadas em um GitHub Actions fluxo de trabalho. Também é possível transmitir o token de acesso de instalação para uma ação personalizada que requer um token.

1. Registre um GitHub App. Conceda ao registro GitHub App as permissões necessárias para acessar os recursos desejados. Para saber mais, confira Registrando um aplicativo GitHub e Escolhendo permissões para um aplicativo GitHub.

2. Armazene o ID do cliente do(a) GitHub App como uma variável de configuração GitHub Actions. Você pode encontrar o ID do cliente na página de configurações do seu aplicativo. A ID do cliente é diferente da ID do aplicativo. Para obter mais informações sobre como navegar até a página de configurações do seu GitHub App, consulte Modificando um registro de 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 Gerenciando 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 na conta correta e conceda permissões e acesso a quaisquer repositórios que você queira que seu fluxo de trabalho acesse. Para saber mais, confira Instalando seu próprio aplicativo GitHub.

5. Em seu GitHub Actions fluxo de trabalho, crie um token de acesso de instalação, que você pode usar para fazer solicitações de API.

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

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

   No fluxo de trabalho a seguir, substitua APP_CLIENT_ID pelo nome da variável de configuração em que você armazenou a ID do cliente. 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@v3
        with:
          client-id: ${{ vars.APP_CLIENT_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@v3
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

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