Migración de aplicaciones de OAuth a aplicaciones de GitHub

Obtén información de las ventajas de migrar una OAuth app a una GitHub App y aprende a migrar una OAuth app.

En este artículo

Ventajas de migrar de OAuth apps a GitHub Apps

Las GitHub Apps son la manera recomendada de realizar la integración con GitHub. Las GitHub Apps ofrecen muchas ventajas frente a las OAuth apps, entre las que se incluyen las siguientes:

  • 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 GitHub Apps.

Conversión de una OAuth app en una GitHub App

En los pasos siguientes, se proporciona información general sobre cómo migrar de una OAuth app a una GitHub App. Los pasos específicos dependen de la aplicación.

1. Revisa la OAuth app

Vuelve a familiarizarte con el código de la OAuth app. Las solicitudes de API que la OAuth app realiza te ayudarán a decidir qué permisos seleccionar para la GitHub App.

Además, hay algunos puntos de conexión de API REST que no están disponibles para OAuth apps. Comprueba que los puntos de conexión de REST que usas estén disponibles para las GitHub Apps; para ello, revisa Puntos de conexión disponibles para tokens de acceso de instalación de aplicaciones de GitHub.

2. Registra una GitHub App

Registra una GitHub App nueva. Para más información, consulta Registro de una instancia de GitHub App.

En comparación con una OAuth app, tienes más control sobre la configuración de la GitHub App. Algunas adiciones clave son:

  • A diferencia de una OAuth app, que siempre actúa en nombre de un usuario, puedes hacer que la GitHub App realice acciones en su propio nombre o en nombre de un usuario. Si no quieres que la GitHub App nueva realice acciones en nombre de un usuario, puedes 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.

  • Puedes utilizar webhooks para notificar a la GitHub App cuando se produzcan eventos específicos. A diferencia de los webhooks de OAuth apps, que debes configurar a través de la API de cada repositorio u organización, los webhooks están integrados en las GitHub Apps. Al registrar la GitHub App, puedes seleccionar los eventos de webhook que deseas recibir. Además, si la OAuth app usa actualmente el sondeo para determinar si se produjo un evento, considera la posibilidad de suscribirte a webhooks en su lugar para ayudar a que la GitHub App permanezca dentro del límite de frecuencia. Para más información, consulta Uso de webhooks con aplicaciones de GitHub.

  • Con una OAuth app, se solicitan ámbitos cuando un usuario autoriza la aplicación. Con una GitHub App, especificas 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 puntos de conexión de la API REST y a los eventos de webhook, por lo que puedes determinar fácilmente los permisos que necesita la GitHub App para acceder a un punto de conexión específico de la API REST 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 hayas registrado una GitHub App, adapta el código de la OAuth app anterior para que funcione con la GitHub App actual.

Actualización de la autenticación

Deberás actualizar el código de la aplicación para controlar la autenticación de API para la GitHub App. Una GitHub App se puede autenticar de tres maneras:

Si usas la biblioteca Octokit.js oficial de GitHub, puedes usar el objeto App integrado que se va a autenticar. 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

Revisa las diferencias en los límites de frecuencia entre las OAuth apps y las GitHub Apps. Las GitHub Apps usan reglas flexibles para los límites de frecuencia, que pueden 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 el uso de webhooks con la GitHub App, consulta 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

Prueba la GitHub App nueva para asegurarte de que el código funciona según lo previsto.

4. Haz pública la GitHub App nueva

Si quieres que otras cuentas puedan usar la GitHub App nueva, asegúrate de que la aplicación sea pública. Si deseas que la GitHub App sea más reconocible, coloca la aplicación en GitHub Marketplace. Para más información, consulta Acerca de Marketplace de GitHub para aplicaciones y Hacer pública o privada a una GitHub App.

5. Indica a los usuarios que migren

Una vez que la aplicación GitHub App nueva esté lista, indica a los usuarios de la OAuth app anterior que migren a la GitHub App nueva. No puedes migrar automáticamente a los usuarios. Cada usuario puede instalar y autorizar la GitHub App por sí mismo.

Como propietario de la aplicación, debes incluir llamadas a la acción para incentivar a los usuarios a que instalen o autoricen la GitHub App nueva y revoquen la autorización de la OAuth app anterior. También debes actualizar cualquier elemento de la interfaz de usuario o documentación.

Indícale a los usuarios que instalen la GitHub App

Si quieres que la GitHub App realice solicitudes de API en su propio nombre o acceda a los recursos de la organización o el repositorio, el usuario debe instalar la 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 le concede los permisos de la organización y el repositorio que solicitó.

Para ayudar a los usuarios a instalar la GitHub App, puedes agregar un vínculo a la página web de la aplicación en la que los usuarios pueden hacer clic para instalar la GitHub App. El formato de la dirección URL de instalación es https://github.com/apps/YOUR_APP_NAME/installations/new. Reemplaza YOUR_APP_NAME por el nombre alternativo de la instancia de GitHub App, que puedes encontrar en el campo "Vínculo público" de la página de configuración de dicha instancia.

Para seleccionar previamente los repositorios a los que tenía acceso la OAuth app, puedes anexar parámetros de consulta y /permissions a la dirección URL de instalación. Esto ayuda a los usuarios a conceder a la GitHub App acceso a los repositorios a los que ya tiene acceso la OAuth app. Los parámetros de consulta son los siguientes:

  • suggested_target_id: el identificador del usuario o de la organización que instala la 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 los repositorios a los que tiene acceso la OAuth app, usa los puntos de conexión Enumerar los repositorios para el usuario autenticado y Enumerar los repositorios de una organización.

Por ejemplo: https://github.com/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 más información sobre la instalación de las GitHub Apps, consulta Instalación de una instancia de GitHub App desde GitHub Marketplace en tu cuenta personal, Instalación de una instancia de GitHub App desde GitHub Marketplace en las organizaciones, Instalación de una instancia de GitHub App desde un tercero y Instalación de tu propia instancia de GitHub App.

Indícale a los usuarios que autoricen la aplicación

Si quieres que la 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 más información sobre cómo autorizar GitHub Apps, consulta Autorizar GitHub Apps.

Incentiva a los usuarios para que revoquen el acceso de OAuth app

También debes incentivar a los usuarios para que revoquen el acceso de la OAuth app anterior. Esto te ayudará a salir completamente de la OAuth app y a mantener seguros los datos de los usuarios. Para más información, consulta Revisión de las aplicaciones autorizadas de OAuth.

Actualiza toda interfaz o documentación

Debes actualizar toda documentación o interfaz de usuario relacionada con la aplicación a fin de reflejar el cambio de una OAuth app a una GitHub App.

6. Quita webhooks de la OAuth app anterior

Cuando un usuario instala la GitHub App y concede acceso a un repositorio, debes quitar los webhooks de la OAuth app anterior. Si la GitHub App nueva y la OAuth app anterior responden a webhooks del mismo evento, es posible que el usuario observe un comportamiento duplicado.

Para quitar webhooks de repositorio, puedes escuchar el webhook installation_repositories con la acción added. Cuando la GitHub App recibe ese evento, puedes usar la API REST para eliminar el webhook de esos repositorios para la 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 la GitHub App recibe ese evento para una organización, puedes usar la API REST para borrar el webhook de esa organización los repositorios correspondientes para la 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. Elimina la OAuth app anterior

Una vez que los usuarios hayan migrado a la GitHub App nueva, debes eliminar la OAuth app anterior. Esto ayudará a evitar que se abuse de las credenciales de la OAuth app. Esta acción también revocará todas las autorizaciones restantes de la OAuth app. Para más información, consulta Eliminación de una aplicación de OAuth. Si la OAuth app aparece en GitHub Marketplace, es posible que tengas que ponerte primero en contacto con Soporte de GitHub para quitar la aplicación del marketplace.