Ventajas de migrar de OAuth apps a GitHub Apps
GitHub Apps son la manera recomendada de integrar con GitHub. GitHub Apps ofrecen muchas ventajas frente a OAuth apps, entre ellas:
- Características de seguridad mejoradas, como permisos específicos, elección sobre el acceso al repositorio y tokens de corta duración
- La capacidad de actuar de manera independiente o en nombre de un usuario
- Límites de frecuencia escalables
- Webhooks integrados
Para más información, consulta Acerca de la creación de aplicaciones de GitHub.
Conversión de un objeto OAuth app en GitHub App
Los siguientes pasos ofrecen una visión general de cómo migrar de un OAuth app a un GitHub App. Los pasos específicos dependen de la aplicación.
1. Revise su OAuth app
Vuelva a familiarizarse con el código de su OAuth app. Las solicitudes a la API que realice tu OAuth app te ayudarán a decidir qué permisos seleccionar para tu GitHub App.
Además, hay algunos puntos de conexión de API REST que no están disponibles para OAuth apps. Compruebe que los extremos REST que utilice estén disponibles para GitHub Apps consultando Puntos de conexión disponibles para los tokens de acceso para la instalación de aplicaciones de GitHub.
2. Registre un GitHub App
Registre un nuevo GitHub App. Para más información, consulta Registro de una aplicación de GitHub.
Comparado con un OAuth app, tienes más control sobre la configuración de GitHub App. Algunas adiciones clave son:
-
A diferencia de un OAuth app, que siempre actúa en nombre de un usuario, puedes hacer que tu GitHub App realice acciones por sí mismo o en nombre de un usuario. Si no desea que el nuevo GitHub App realice acciones en nombre de un usuario, puede omitir la configuración "Identificación y autorización de usuarios". Para más información, consulta Acerca de la autenticación con una aplicación de GitHub.
-
Puede usar webhooks para notificar a su GitHub App cuando se produzcan eventos específicos. A diferencia de los webhooks para OAuth apps, que debe configurar a través de la API para cada repositorio u organización, los webhooks están integrados en GitHub Apps. Al registrar su GitHub App, puede seleccionar los eventos de webhook que desea recibir. Además, si OAuth app utiliza actualmente sondeo para determinar si se ha producido algún evento, considere suscribirse a webhooks en su lugar para ayudar a GitHub App a mantenerse dentro del límite de tasa. Para más información, consulta Uso de webhooks con aplicaciones de GitHub.
-
Con un OAuth app, solicitas alcances cuando un usuario autoriza tu aplicación. Con un GitHub App, se especifican los permisos en la configuración de la aplicación. Estos permisos son más pormenorizados que los ámbitos y te permiten seleccionar solo los permisos que necesita la aplicación. Además, estos permisos se asignan a los puntos de conexión de la API REST y a los eventos de webhook, por lo que puede determinar fácilmente qué permisos GitHub App necesita para acceder a un punto de conexión de API REST específico o suscribirse a un webhook específico. Actualmente, los permisos no están documentados para las solicitudes de GraphQL. Para más información, consulta Elección de permisos para una aplicación de GitHub.
3. Modifica el código de la aplicación
Una vez que haya registrado un GitHub App, adapte el código del antiguo OAuth app para trabajar con el nuevo GitHub App.
Actualización de la autenticación
Tendrá que actualizar el código de su aplicación para gestionar la autenticación de la API para su GitHub App. Un GitHub App puede autenticarse de tres maneras:
- Como la propia aplicación, para obtener o modificar detalles sobre el GitHub App registro o para crear un token de acceso de instalación. Para más información, consulta Autenticación como una aplicación de GitHub.
- Como instalación de aplicación, para realizar acciones en su propio nombre. Para más información, consulta Autenticación como una instalación de una aplicación de GitHub.
- En nombre de un usuario, para atribuir acciones a un usuario. Para más información, consulta Autenticación con una aplicación de GitHub en nombre de un usuario.
Si usa GitHubla biblioteca oficial de Octokit.js, puede usar el objeto integrado App para autenticarse. Para obtener ejemplos, consulta Scripting con la API de REST y JavaScript y Creación de una aplicación de GitHub que responda a eventos de webhook.
Revisión de los límites de frecuencia
Revise las diferencias en los límites de velocidad entre OAuth apps y GitHub Apps. GitHub Apps use reglas deslizantes para los límites de velocidad, lo que puede aumentar en función del número de repositorios y el número de usuarios de la organización. Para más información, consulta Límites de frecuencia para aplicaciones de GitHub.
Si es posible, considera la posibilidad de utilizar solicitudes condicionales y suscribirte a webhooks en lugar de sondeos para mantenerte dentro de los límites de frecuencia. Para más información sobre las solicitudes condicionales, consulta Procedimientos recomendados para usar la API de REST. Para obtener más información sobre cómo usar webhooks con su GitHub App, consulte Uso de webhooks con aplicaciones de GitHub y Creación de una aplicación de GitHub que responda a eventos de webhook.
Probar el código
Pruebe el nuevo GitHub App para asegurarse de que el código funciona según lo previsto.
4. Da a conocer tu nuevo GitHub App
Si quiere que otras cuentas puedan usar el nuevo GitHub App, asegúrese de que la aplicación es pública.Para obtener más información, consulte Hacer que una aplicación de GitHub sea pública o privada.
5. Indica a los usuarios que migren
Una vez que el nuevo GitHub App esté listo, indique a los usuarios del antiguo OAuth app que migre a su nuevo GitHub App. No puedes migrar automáticamente a los usuarios. Cada usuario debe instalar y/o autorizar su GitHub App por su cuenta.
Como propietario de la aplicación, debe incluir llamadas a la acción para animar a los usuarios a instalar o autorizar el nuevo GitHub App y revocar la autorización para el antiguo OAuth app. También debes actualizar cualquier elemento de la interfaz de usuario o documentación.
Pida a los usuarios que instalen su GitHub App
Si desea que GitHub App realice solicitudes de API en nombre propio o acceda a los recursos de la organización o del repositorio, el usuario debe instalar GitHub App. Cuando un usuario instala una GitHub App en su cuenta u organización, elige los repositorios a los que puede acceder la aplicación y concede a la aplicación los permisos de organización y repositorio que solicitó.
Para ayudar a los usuarios a instalar su GitHub App, puede añadir un vínculo a la página web de su aplicación en el que los usuarios puedan hacer clic para instalar la GitHub App. El formato de la dirección URL de instalación es http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new. Reemplaza YOUR_APP_NAME por el nombre en formato slug de tu GitHub App, que puedes encontrar en el campo "Enlace público" de la página de configuración de tu GitHub App.
Para seleccionar previamente los repositorios OAuth app a los que tenía acceso, puede anexar /permissions y consultar parámetros a la dirección URL de instalación. Esto ayuda a los usuarios a conceder acceso a su GitHub App a los repositorios a los que su OAuth app ya tiene acceso. Los parámetros de consulta son los siguientes:
suggested_target_id: El identificador del usuario u organización que está instalando tu GitHub App. Este parámetro es obligatorio.repository_ids[]: los identificadores de repositorio que se van a seleccionar para la instalación. Si se omite, se seleccionan todos los repositorios. La cantidad máxima de repositorios que se pueden pre-seleccionar es de 100. Para obtener una lista de repositorios a los que su OAuth app tiene acceso, use los endpoints List repositories for the authenticated user y List organization repositories.
Por ejemplo: http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.
Para obtener más información sobre cómo instalar GitHub Apps, consulte Instalación de una instancia de GitHub App desde un tercero y Instalación de su propia aplicación de GitHub.
Indícale a los usuarios que autoricen la aplicación
Si desea que GitHub App realice solicitudes de API en nombre de un usuario, el usuario debe autorizar la aplicación. Cuando un usuario autoriza una aplicación, le concede permiso para actuar en su nombre y concede los permisos de usuario que la aplicación ha solicitado. Si la aplicación está instalada en una cuenta de organización, cada usuario de esa organización debe autorizar la aplicación para que esta actúe en su nombre.
Para solicitar a los usuarios que autoricen la aplicación, los llevarás a través del flujo de aplicación web o del flujo de dispositivo. Para más información, consulta Generación de un token de acceso de usuario para una aplicación de GitHub.
Para obtener más información sobre cómo autorizar GitHub Apps, vea Autorización de aplicaciones GitHub.
Anime a sus usuarios a revocar OAuth app el acceso
También debería animar a sus usuarios a revocar el acceso a su antiguo OAuth app. Esto le ayudará a dejar atrás por completo su OAuth app y a mantener seguros los datos de sus usuarios. Para más información, consulta Revisión de las aplicaciones autorizadas de OAuth.
Actualiza toda interfaz o documentación
Debería actualizar cualquier interfaz de usuario o documentación relacionada con su aplicación para reflejar el cambio de OAuth app a GitHub App.
6. Eliminar webhooks de tu antiguo OAuth app
Cuando un usuario instala su GitHub App y concede acceso a un repositorio, debería eliminar los webhooks de su antiguo OAuth app. Si el nuevo GitHub App y el anterior OAuth app responden a webhooks para el mismo evento, el usuario puede observar un comportamiento duplicado.
Para quitar webhooks de repositorio, puedes escuchar el webhook installation_repositories con la acción added. Cuando su GitHub App reciba ese evento, puede usar la API de REST para eliminar el webhook de esos repositorios para su OAuth app. Para más información, consulta Eventos y cargas de webhook y Puntos de conexión de la API de REST para los webhooks de repositorio.
De manera similar, para quitar webhooks de organización, puedes escuchar el webhook installation con la acción created. Cuando su GitHub App reciba ese evento para una organización, puede usar la API de REST para eliminar el webhook en esa organización y los repositorios correspondientes de su OAuth app. Para más información, consulta Eventos y cargas de webhook, Puntos de conexión de API REST para webhooks de organización y Puntos de conexión de la API de REST para los webhooks de repositorio.
7. Eliminar tu antiguo OAuth app
Una vez que los usuarios hayan migrado al nuevo GitHub App, debe eliminar el antiguo OAuth app. Esto ayudará a evitar el abuso de las credenciales de OAuth app. Esta acción también revocará todas las OAuth appautorizaciones restantes. Para más información, consulta Eliminación de una aplicación de OAuth. Si su OAuth app está publicada en GitHub Marketplace, es posible que deba ponerse en contacto con Soporte de GitHub para quitar primero su aplicación del marketplace.