Automatización de instalaciones de aplicaciones en las organizaciones de la empresa

Introducción

Para automatizar un proceso de forma segura, puede crear un GitHub App propiedad de una cuenta de empresa y, a continuación, instalar la aplicación en la empresa u organización donde tendrá lugar la automatización.

GitHub Apps genera tokens que se pueden usar para autenticar llamadas de API a GitHub en scripts y flujos de trabajo. Estos tokens son adecuados para empresas con requisitos específicos de seguridad y auditoría, ya que son:

• Temporales
• Restringido a cuentas y permisos específicos
• Asociada a la identidad de la aplicación en lugar de a una cuenta de usuario

Una necesidad común para las grandes empresas es mantener una automatización coherente y up-to-date en muchas organizaciones. Para ello, instale una aplicación mediante programación. Por ejemplo, si necesita configurar todas las organizaciones con determinadas directivas y opciones de configuración, puede instalar un GitHub App para esta tarea en cada organización.

En esta guía se muestran los pasos necesarios para instalar de forma programática una GitHub App propietaria de la empresa en una organización. Una vez instalada la aplicación, la usará para crear un nuevo repositorio.

Información general del proceso

En esta guía, usará GitHub CLI para realizar las llamadas a la API necesarias a fin de solicitar tokens de acceso e instalar una aplicación en una organización. En realidad, este proceso formaría parte de un script personalizado adaptado a las necesidades de su empresa.

Realizará lo siguiente:

1. Cree dos aplicaciones propiedad de su cuenta empresarial.
   • Uno tendrá permiso para instalar aplicaciones en organizaciones.
   • El otro tendrá permiso para automatizar un proceso en una organización (en este caso, crear un repositorio).
2. Para obtener un token de acceso con alcance empresarial, autenticar la primera aplicación.
3. Use el token de ámbito empresarial para llamar a una API que instale la aplicación de automatización en una organización.
4. Autentique la aplicación que instaló la organización para obtener un token de acceso con ámbito organizacional.
5. Use el token con ámbito de organización para llamar a una API que cree un repositorio en la organización.

En cada fase, usará un token que solo tenga permiso para realizar acciones específicas en una cuenta específica. Desde una perspectiva de seguridad y auditoría, este enfoque es superior a confiar en un solo token con permiso para realizar acciones en toda la empresa y las organizaciones.

Prerrequisitos

Para seguir esta guía en su propio dispositivo, debe:

• Ser propietario de la empresa.
• Ser propietario de una organización de propiedad empresarial donde realizará la automatización.
• Tenga instalado GitHub CLI para realizar llamadas de API. Consulte Instalación en el repositorio GitHub CLI .
• Tener openssl instalado para generar un token web JSON (JWT). Muchos dispositivos tienen OpenSSL instalado de forma predeterminada. Puede comprobar si ejecuta openssl -v, que devuelve un número de versión si está instalado.
• Use un shell de Unix como Bash, ZSH o Git Bash.

1. Preparación para generar un JWT

Para solicitar un token de acceso desde una aplicación, necesita un token web JSON (JWT) generado a partir del identificador de cliente y la clave privada de la aplicación. Muchos lenguajes de programación tienen métodos integrados para generar un JWT. En este tutorial, usará un script de Bash para generar un JWT desde la línea de comandos mediante openssl.

1. Copie el contenido del script de Bash para generar un JWT desde Generación de un token web JSON (JWT) para una aplicación de GitHub.

2. Guarde el contenido en un archivo nuevo en el directorio principal, denominado gen-jwt.sh.

3. Convierta el script en ejecutable.

   Shell

   chmod +x ~/gen-jwt.sh
   

2. Creación de dos aplicaciones empresariales

GitHub Apps solo puede generar tokens con permisos detallados y los niveles de cuenta que permita. En este paso, creará dos aplicaciones de propiedad empresarial: una con permiso de nivel empresarial para instalar aplicaciones y otra con permiso de nivel de organización para crear un repositorio.

a) Creación de la aplicación del instalador

La "aplicación del instalador" se instalará en la cuenta de empresa y tendrá permiso para instalar la otra aplicación en una organización.

1. Cree una aplicación en su cuenta de empresa.

   1. Vaya a la configuración de la cuenta empresarial.
   2. En la barra lateral de la izquierda, haga clic en GitHub Apps .
   3. Haga clic en Nuevo GitHub App.

2. Puede dejar la mayoría de los valores como predeterminados, excepto:

   • Llame a la app YOUR-HANDLE-installer-app, y reemplace YOUR-HANDLE por su nombre de usuario de GitHub.
   • Establezca la opción "Url de la página principal" en https://github.com.
   • Desmarque Invalidar tokens de autorización de usuario y, en "Webhook", desmarque Activo.
   • En "Permisos de empresa", conceda a la aplicación permisos de lectura y escritura para las instalaciones de la organización Enterprise.

3. Después de crear la aplicación, copie el identificador de cliente y guárdelo como una variable denominada INSTALLER_APP_CLIENT_ID. Por ejemplo, en la línea de comandos:

   Shell

   export INSTALLER_APP_CLIENT_ID='abcde12345'
   

4. En la página de la aplicación, desplácese hacia abajo y haga clic en Generar una clave privada. Se descargará el archivo de clave privada.

5. Tome nota de la ruta de acceso del archivo, que tendrá un aspecto similar a ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem.

6. En la barra lateral izquierda de la página de la aplicación, haga clic en Instalar aplicación y, a continuación, instale la nueva aplicación en la cuenta empresarial. La instalación de una aplicación concede permiso a la aplicación para realizar acciones en la cuenta.

7. Examine la dirección URL del explorador para buscar el identificador de instalación de la aplicación. Se trata de una cadena de números al final de la /enterprises/ENTERPRISE/settings/installations/ID dirección URL. Guárdelo como variable INSTALLER_APP_INSTALL_ID .

   Shell

   export INSTALLER_APP_INSTALL_ID='12345678'
   

8. Guarde el nombre de la empresa donde se instala la aplicación como una variable.

   Shell

   export ENTERPRISE='octo-enterprise'
   

b. Creación de la aplicación de automatización

La "aplicación de automatización" se instalará en una organización y tendrá permiso para crear repositorios en esa organización. En realidad, concedería a esta aplicación los permisos necesarios para automatizar un proceso en las organizaciones.

1. Cree una aplicación en su cuenta de empresa.

   • Llame a la app YOUR-HANDLE-automation-app, y reemplace YOUR-HANDLE por su nombre de usuario de GitHub.
   • Establezca la opción "Url de la página principal" en https://github.com.
   • Desmarque Invalidar tokens de autorización de usuario y, en "Webhook", desmarque Activo.
   • En "Permisos de repositorio", asigne a la aplicación permisos de lectura y escritura para Administración.

2. Después de crear la aplicación, copie el identificador de cliente y guárdelo como variable AUTOMATION_APP_CLIENT_ID .

   Shell

   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   

3. Desplácese hacia abajo y haga clic en Generar una clave privada. Se descargará el archivo de clave privada.

4. Tome nota de la ruta de acceso del archivo, que tendrá un aspecto similar a ~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem.

5. Guarde el nombre de la organización donde se instalará la aplicación como una variable.

   Shell

   export ORG='octo-org'
   

3. Autenticar la aplicación del instalador

La autenticación de una aplicación permite obtener un token con el ámbito y los permisos definidos al registrar la aplicación. En este caso, obtendrá un token para la aplicación del instalador, que le dará permiso para instalar la aplicación de automatización en una organización.

1. Genere un JWT mediante el script de Bash que guardó. Por ejemplo:

   Shell

   ~/gen-jwt.sh $INSTALLER_APP_CLIENT_ID ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem
   

2. Copie el JWT (la cadena larga después de JWT= ) y guárdelo como una variable.

   Shell

   export INSTALL_JWT='abcde12345'
   

3. Use el JWT para autenticar una solicitud de un token de acceso de instalación. En este paso se utiliza el punto de conexión de la API Crear un token de acceso de instalación para una aplicación y se requiere el ID de instalación de la aplicación.

   Shell

   gh api --method POST "/app/installations/$INSTALLER_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $INSTALL_JWT"
   

4. Debería ver un objeto JSON que contiene una token propiedad . Copie el token de acceso (el valor de la token propiedad, sin comillas) y guárdelo como variable INSTALLER_APP_INSTALL_TOKEN .

   Shell

   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   

4. Instalación de la aplicación de automatización

El token de acceso de instalación que acaba de recibir le da permiso para llamar a la API para instalar aplicaciones en una organización. Aquí, usaremos el token para instalar la aplicación de automatización (la segunda aplicación que creó) en una organización específica. En realidad, podría llamar a esta API varias veces para instalar una aplicación en varias organizaciones.

1. Ejecute el siguiente comando. Estamos usando la opción Instalar una aplicación de GitHub en un punto de conexión de API de la organización propiedad de la empresa , autenticando con el token de instalación que acaba de solicitar y pasando el identificador de cliente de la aplicación de automatización que queremos instalar.

   Shell

   gh api --method POST \
     "/enterprises/$ENTERPRISE/apps/organizations/$ORG/installations" \
     --header "Authorization: Bearer $INSTALLER_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "client_id=$AUTOMATION_APP_CLIENT_ID" \
     --field "repository_selection=all"
   

2. Si se ejecuta correctamente, debería ver muchas propiedades devueltas, empezando por el ID de instalación de la aplicación.

   Para comprobar que la aplicación se instaló correctamente, vaya a https://github.com/organizations/ORG/settings/installations, reemplazando ORG por el nombre de la organización. Debería ver la aplicación recién instalada en la página.

3. Busque el identificador de instalación de la nueva instalación y guárdelo como AUTOMATION_APP_INSTALL_ID. Para buscar el identificador, puede copiar la primera propiedad ID devuelta por la API o hacer clic en Configurar junto a la instalación de la aplicación en la interfaz de usuario y copiar el identificador de la dirección URL.

   Shell

   export AUTOMATION_APP_INSTALL_ID='12345678'
   

5. Autenticación de la aplicación de automatización

Al igual que ha autenticado la aplicación del instalador para obtener un token de ámbito empresarial, ahora debe realizar el mismo proceso para la aplicación de automatización. Esto le proporcionará un token con ámbito de organización con permiso para crear repositorios.

1. Genere un JWT con el identificador de cliente y la clave privada de la aplicación de automatización. Por ejemplo:

   Shell

   ~/gen-jwt.sh $AUTOMATION_APP_CLIENT_ID ~/octocat-automation-app.2025-10-08.private-key.pem
   

2. Copie el JWT (la cadena larga después de JWT= ) y guárdelo como una variable.

   Shell

   export AUTO_JWT='abcde12345'
   

3. Use JWT para autenticar una solicitud de un token de acceso de instalación, esta vez pasando el identificador de instalación y JWT para la aplicación de automatización recién instalada.

   Shell

   gh api --method POST "/app/installations/$AUTOMATION_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $AUTO_JWT"
   

4. Copie el nuevo token de acceso de instalación y guárdelo como variable AUTOMATION_APP_INSTALL_TOKEN .

   Shell

   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   

6. Automatizar un proceso

El token de instalación que acaba de recibir le da permiso para crear un repositorio en la organización donde está instalada la aplicación.

1. Ejecute el siguiente comando. Observe que estamos autenticando con el token de instalación que acabamos de obtener.

   Shell

   gh api --method POST \
     "/orgs/$ORG/repos" \
     --header "Authorization: Bearer $AUTOMATION_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "name=automatic-repo" \
     --field "description=Repository created automatically using GitHub App automation" \
     --field "private=false" \
     --field "auto_init=true"
   

2. Para comprobar que el repositorio se creó correctamente, vaya a https://github.com/orgs/ORG/repositories, reemplazando ORG por el nombre de la organización.

          <a href="https://docs.github.io/success-test/yes.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline">
          <span>Sí</span></a><a href="https://docs.github.io/success-test/no.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline"><span>No</span></a>

7. Desinstalar las aplicaciones

Para mayor seguridad, desinstale las aplicaciones de la empresa y la organización. Esto revocará todos los tokens asociados a las aplicaciones. Para instrucciones, consulta Revisión y modificación de aplicaciones de GitHub instaladas.

Pasos siguientes

Ha visto cómo instalar una aplicación mediante programación en organizaciones y ejecutar una automatización. Ahora, debe estar listo para automatizar un proceso real en varias organizaciones. Para obtener más información sobre lo que pueden hacer las aplicaciones, consulte Acerca de la creación de aplicaciones de GitHub.