Acerca de las GitHub Apps
Una GitHub App es un tipo de integración que puedes crear para interactuar con GitHub y extender su funcionalidad. Puedes crear una GitHub App para proporcionar flexibilidad y reducir la fricción en los procesos, sin que sea necesario que los usuarios inicien sesión o creen cuentas de servicio.
Entre los casos de uso comunes para GitHub Apps, se incluyen:
- Automatización de tareas o procesos en segundo plano
- Compatibilidad con "Iniciar sesión con GitHub," que permite que los usuarios inicien sesión con su cuenta de GitHub para proporcionar su identidad en el ecosistema
- Como herramienta para desarrolladores, permitir que los usuarios trabajen con GitHub mediante el inicio de sesión en tu GitHub App, que luego puede actuar en su nombre
- Integración de la herramienta o servicio externo con GitHub
GitHub Apps son actores independientes dentro de GitHub. Una GitHub App actúa en su propio nombre, lo que significa que no es necesario que mantengas una cuenta de servicio o bot como usuario independiente. También pueden autenticarse como usuario y actuar en nombre del usuario, con los permisos que se le concedieron.
Si quieres que la aplicación responda a los eventos en GitHub, la aplicación se debe suscribir a los webhooks. Por ejemplo, puede que quieras que la aplicación deje un comentario cuando se abra una PR. Para obtener más información, vea «Uso de webhooks con aplicaciones de GitHub».
Durante el desarrollo, puedes ejecutar la aplicación localmente. Una vez que la aplicación esté lista para su uso en producción, debes implementarla en un servidor dedicado. Por ejemplo, puedes usar Azure App Service.
Permisos y visibilidad para GitHub Apps
Las GitHub Apps se pueden instalar directamente en las cuentas de organización y personales, y se les puede dar acceso a repositorios específicos. Vienen con webhooks integrados y con permisos específicos y delimitados. Cuando configuras una GitHub App, puedes seleccionar permisos específicos para la aplicación. Estos permisos determinan lo que la aplicación puede hacer a través de la API de GitHub, lo que pueden hacer en nombre de un usuario que haya iniciado sesión y qué webhooks puede recibir la aplicación. Cuando se instala la aplicación en una cuenta de usuario o de organización, la persona que la instala decide a qué repositorio puede acceder la aplicación en esa cuenta. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».
Predeterminadamente, solo los propietarios de la organización pueden administrar los ajustes de las GitHub Apps en una organización. Para permitir que otros usuarios cambien la configuración del desarrollador de aplicaciones de GitHub que pertenecen a la organización, un propietario puede concederles permisos de administrador de aplicaciones de GitHub. Los administradores de aplicaciones de GitHub no pueden administrar aplicaciones de terceros. Para más información sobre cómo agregar y quitar administradores de aplicaciones de GitHub en la organización, consulta "Roles en una organización".
Puedes establecer la visibilidad de la aplicación para controlar quién puede instalarla. Puedes hacerla pública para que otros usuarios u organizaciones de GitHub puedan instalar la aplicación, o bien hacerla privada para que solo puedas instalarla en la cuenta propietaria de la aplicación. Para obtener más información, vea «Hacer pública o privada a una GitHub App».
Cuando usar las GitHub Apps
Al compilar una integración, debes considerar la posibilidad de usar una GitHub App en los escenarios siguientes en lugar de una OAuth App, un personal access token o las GitHub Actions.
Uso de una GitHub App en lugar de una OAuth App
En general, se prefieren las GitHub App a las OAuth App.
Para obtener más información, vea «Diferencias entre aplicaciones de GitHub y aplicaciones de OAuth».
Para información sobre cómo migrar una OAuth App existente a una GitHub App, consulta "Migrating OAuth Apps to GitHub Apps".
Las GitHub App ofrecen una seguridad mejorada
Las GitHub App proporcionan más control sobre lo que puede hacer la aplicación. En lugar de los ámbitos amplios que las OAuth App utilizan, las GitHub App utilizan permisos específicos. Por ejemplo, si tu aplicación necesita leer el contenido de un repositorio, una OAuth App requeriría el ámbito repo, que también permitiría a la aplicación editar la configuración y el contenido del repositorio. Una GitHub App puede solicitar acceso de solo lectura al contenido del repositorio, el que no permitirá que la aplicación realice acciones que necesiten más privilegios, como editar la configuración o el contenido del repositorio.
Las GitHub App también ofrecen más control sobre el acceso al repositorio. Con una GitHub App, el propietario de la organización o el usuario que instaló la aplicación puede decidir a qué repositorios puede acceder la aplicación. Por el contrario, una OAuth App puede acceder a cada repositorio a los que puede acceder el usuario que autorizó la aplicación.
Las GitHub App utilizan tokens de corta duración. Si se filtra el token, será válido durante un período más breve, lo que reduce el daño que pueda haber. Por el contrario, los tokens de una OAuth App no expiran hasta que la persona que autorizó la OAuth App los revoca.
Estas características de seguridad ayudan a proteger la seguridad de GitHub App al limitar el daño que se podría hacer si se hubieran filtrado las credenciales de la aplicación. Además, esto permite que las organizaciones con directivas de seguridad más estrictas usen la aplicación.
Las GitHub App pueden actuar de manera independiente o en nombre de un usuario
Las GitHub App pueden actuar de manera independiente de un usuario. Esto resulta beneficioso para las automatizaciones que no requieren la entrada del usuario.
De manera similar a lo que ocurre con las OAuth App, las GitHub App de todos modos pueden realizar acciones en nombre de un usuario. A diferencia de lo que ocurre con las OAuth App, que no indican que la aplicación hizo la acción, las GitHub App indican que la aplicación hizo la acción en nombre del usuario.
Las GitHub App no están vinculadas a una cuenta de usuario y no consumen un puesto de GitHub Enterprise Server. Las GitHub App permanecen instaladas aunque la persona que instaló inicialmente la aplicación deje la organización. Esto permite que las integraciones sigan funcionando incluso si las personas dejan el equipo.
Las GitHub App tienen límites de frecuencia escalables
El límite de frecuencia de las GitHub App con un token de acceso de instalación se escala con el número de repositorios y el número de usuarios de la organización. Por el contrario, las OAuth Apps tienen límites de frecuencia inferiores y no se escalan. Para obtener más información, vea «Límites de frecuencia para aplicaciones de GitHub».
Las GitHub App tienen webhooks integrados
Las GitHub App tienen webhooks centralizados integrados. Las GitHub App pueden recibir eventos de webhook para todos los repositorios y las organizaciones a los que puede acceder la aplicación. Por el contrario, las OAuth App deben configurar webhooks de manera individual para cada repositorio y organización.
El acceso a la API difiere ligeramente
En general, las GitHub App y las OAuth App pueden hacer las mismas solicitudes de API. Sin embargo, hay algunas diferencias:
- La API REST para administrar las ejecuciones de comprobación y los conjuntos de comprobación solo está disponible para las GitHub App.
- Los recursos de empresa solo están disponibles para OAuth App.
- Algunas solicitudes pueden devolver datos incompletos en función de los permisos y el acceso al repositorio que se concedió a una GitHub App. Por ejemplo, si la aplicación realiza una solicitud para obtener todos los repositorios a los que un usuario puede acceder, la respuesta solo incluirá los repositorios a los que también se concedió acceso a la aplicación.
Para más información de los puntos de conexión de la API REST que están disponibles para las GitHub App, consulta "Terminales disponibles para las Apps de GitHub".
Elección entre una GitHub App o una personal access token
Si quieres acceder a los recursos de GitHub en nombre de un usuario o una organización, o si prevés una integración de larga duración, te recomendamos compilar una GitHub App.
Puedes usar personal access tokens para scripts de corta duración o pruebas de API. Como personal access token está asociado a un usuario, la automatización podría interrumpirse si el usuario ya no tiene acceso a los recursos que necesita. Una GitHub App instalada en una organización no depende de un usuario. Además, a diferencia de un usuario, GitHub App no consume un puesto de GitHub.
GitHub admite dos tipos de personal access tokens, pero te recomienda usar fine-grained personal access token, siempre que sea posible, en lugar de personal access tokens. Para más información sobre personal access tokens, consulta "Managing your personal access tokens".
Elección entre una GitHub App o una GitHub Actions
Tanto GitHub Apps como GitHub Actions proporcionan formas de crear herramientas de automatización y flujo de trabajo.
GitHub Actions proporcionan automatización que puede realizar trabajos como la integración continua, las tareas de implementación y la administración de proyectos en un repositorio. Se ejecutan directamente en máquinas ejecutoras hospedadas en GitHub o ejecutores autohospedados que el administrador configura. GitHub Actions no se ejecutan de manera persistente, sino que en respuesta a eventos que se producen en su repositorio y solo tienen acceso a los recursos del repositorio para los que están configurados. Sin embargo, se pueden compartir entre repositorios y organizaciones, lo que permite a los desarrolladores reutilizar y modificar las acciones existentes para satisfacer sus necesidades. GitHub Actions también incluyen la administración de secretos integrada, que puedes usar para interactuar de manera segura con servicios de terceros y administrar con seguridad las claves de implementación.
Las GitHub Apps se ejecutan de manera persistente en una infraestructura de proceso o servidor que proporcionas y reaccionan a eventos de webhook, así como a eventos de fuera del ecosistema de GitHub. Son una buena opción para las operaciones que abarcan varios repositorios u organizaciones, o para proporcionar servicios hospedados a otras organizaciones. Una GitHub App es la mejor opción al crear una herramienta con funciones que se producen principalmente fuera de GitHub o que requieren más tiempo del que se le asigna a una acción para su ejecución.
Para más información sobre cómo se comparan GitHub Actions y GitHub Apps, consulta "Acercad e las acciones personalizadas".
Puedes usar GitHub App para autenticarte en un flujo de trabajo de GitHub Actions si el GITHUB_TOKEN integrado no tiene permisos suficientes. Para obtener más información, vea «Realización de solicitudes de API autenticadas con una aplicación de GitHub en un flujo de trabajo de Acciones de GitHub».
Descripción del tipo de GitHub App que se va a compilar
Hay varias maneras de diseñar una GitHub App que querrás tener en cuenta según la funcionalidad que quieres que tenga la aplicación.
GitHub Apps que actúan en nombre de un usuario
Si quieres que la aplicación realice acciones en nombre de un usuario, debes usar un token de acceso de usuario para la autenticación. Este tipo de solicitud se denomina a veces "usuario a servidor" y significa que la aplicación estará limitada por los permisos que se concedieron a la aplicación, así como el permiso del usuario. Con este patrón, el usuario debe autorizar la aplicación antes de que esta pueda realizar alguna acción. Para obtener más información, vea «Autenticación con una aplicación de GitHub en nombre de un usuario».
Entre los ejemplos de las automatizaciones que podrías crear con una GitHub App, en las que la aplicación actúa en nombre de un usuario, se incluyen las siguientes:
- Una GitHub App que usa GitHub como proveedor de identidades para el ecosistema.
- Una GitHub App que agrega un servicio encima de GitHub.com que podría resultar útil para un usuario de GitHub. Puedes compartir la aplicación con otros desarrolladores a través de GitHub Marketplace o haciendo que la aplicación sea pública.
GitHub Apps que actúan en su propio nombre
Si quieres que la aplicación realice acciones en su propio nombre en lugar de hacerlo en nombre de un usuario, debes usar un token de acceso de instalación para la autenticación. Este tipo de solicitud se denomina a veces "servidor a servidor" y significa que la aplicación estará limitada por los permisos que se concedieron a la aplicación. Para obtener más información, vea «Autenticación como una instalación de una aplicación de GitHub».
Entre los ejemplos de las automatizaciones que podrías crear con una GitHub App, en las que la aplicación actúa en su propio nombre, se incluyen las siguientes:
- Una GitHub App que usa webhooks para reaccionar a un evento dado conjunto de criterios determinado. Por ejemplo, podrías crear una automatización que use los puntos de conexión de la API REST para las etiquetas para agregar una etiqueta a cada incidencia nueva creada en un repositorio, dado un conjunto de criterios determinado.
- Una GitHub App que ayude a los colaboradores del repositorio. Por ejemplo, la aplicación podría publicar recursos útiles después de que un colaborador crea una PR o hace un comentario.
- Una GitHub App que genera tokens de corta duración para proporcionarlos a otras herramientas de CI/CD, o para extraer información de un repositorio.