Realización de solicitudes de API autenticadas con una aplicación de GitHub en un flujo de trabajo de Acciones de GitHub

Acerca de la autenticación de GitHub Actions

Si necesitas realizar solicitudes de API autenticadas en un flujo de trabajo de GitHub Actions o necesitas ejecutar una acción personalizada que requiera un token, debes usar el GITHUB_TOKEN integrado si es posible. Sin embargo, GITHUB_TOKEN solo puedes acceder a los recursos dentro del repositorio del flujo de trabajo. Si necesitas acceder a recursos adicionales, como recursos de una organización o en otro repositorio, puedes usar GitHub App. Para más información sobre por qué podrías usar GitHub App sobre personal access token, consulta "Acerca de la creación de GitHub Apps".

Autenticación con una GitHub App

Para usar una instancia de GitHub App para realizar solicitudes de API autenticadas, debes registrar una instancia de GitHub App, almacenar las credenciales de la aplicación e instalar la aplicación. Una vez hecho esto, puedes usar la aplicación para crear un token de acceso de instalación, que se puede usar para realizar solicitudes de API autenticadas en un flujo de trabajo de GitHub Actions. También puedes pasar el token de acceso de instalación a una acción personalizada que requiera un token.

1. Registra una instancia de GitHub App. Proporciona al registro de tu instancia de GitHub App los permisos necesarios para acceder a los recursos deseados. Para obtener más información, vea «Registro de una instancia de GitHub App» y «Elección de permisos para una aplicación de GitHub».

2. Almacene el identificador de la aplicación de GitHub App como una variable de configuración de GitHub Actions. Puedes encontrar el id. de la aplicación en la página de configuración de la aplicación. El id. de la aplicación es diferente del id. de cliente. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App". Para obtener más información sobre el almacenamiento de variables de configuración, consulte "Almacenamiento de información en variables".

3. Generar una llave privada para tu app. Almacena el contenido del archivo resultante como un secreto. (Almacena todo el contenido del archivo, incluidos -----BEGIN RSA PRIVATE KEY----- y -----END RSA PRIVATE KEY-----). Para más información, consulta "Administración de claves privadas para aplicaciones de GitHub". Para obtener más información sobre cómo almacenar secretos, consulta "Uso de secretos en Acciones de GitHub".

4. Instala la GitHub App en la cuenta de usuario u organización y concédele acceso a todos los repositorios a los que desees que acceda el flujo de trabajo. Para obtener más información, vea «Instalación de tu propia instancia de GitHub App».

5. En el flujo de trabajo de GitHub Actions, crea un token de acceso de instalación que podrás utilizar para realizar solicitudes a la API.

   Para ello, puede usar una acción de propietario de GitHub como se muestra en el ejemplo siguiente. Si prefiere no usar esta acción, puede bifurcar y modificar la acción actions/create-github-app-token o escribir un script para que el flujo de trabajo cree manualmente un token de instalación. Para más información, consulta "Autenticación como una instalación de una aplicación de GitHub".

   En el siguiente flujo de trabajo de ejemplo se usa la acción actions/create-github-app-token para generar un token de acceso de instalación. A continuación, el flujo de trabajo usa el token para realizar una solicitud de API a través de la GitHub CLI.

   En el flujo de trabajo siguiente, reemplace APP_ID por el nombre de la variable de configuración donde se almacenó el identificador de aplicación. Reemplaza APP_PRIVATE_KEY por el nombre del secreto que contiene la clave privada de la aplicación.

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