Registro de una aplicación de GitHub desde un manifiesto

Acerca de los Manifiestos de las GitHub Apps

Cuando alguien crea una aplicación de GitHub desde un manifiesto, únicamente necesitan seguir una URL y asignar un nombre a la aplicación. El manifiesto incluye los permisos, eventos, y URL de los webhooks que se necesiten para registrar la app automáticamente. El flujo del manifiesto crea el registro de la aplicación de GitHub y genera el secreto del webhook, la llave privada (archivo PEM), el secreto de cliente y el identificador de aplicación de GitHub. El usuario que crea el registro de la GitHub App desde el manifiesto tendrá la propiedad del registro de la GitHub App y podrá elegir entre editar la configuración del registro, eliminarlo o transferirlo a otra persona en GitHub.

Puedes usar Probot para empezar a trabajar con manifiestos de aplicación de GitHub o ver una implementación de ejemplo. Consulta "Uso de Probot para implementar el flujo de manifiesto de aplicación de GitHub" para más información.

Aquí te mostramos algunos escenarios en donde podrías utilizar los manifiestos de las aplicaciones de GitHub para crear aplicaciones preconfiguradas:

• Para ayudar a los miembros nuevos del equipo a que se familiaricen rápidamente con el desarrollo de las GitHub Apps.
• Para permitir que otros extiendan una GitHub App utilizando las API de GitHub sin que necesiten configurar dicha app.
• Para crear diseños de referencia de GitHub Apps y compartirlos con la comunidad de GitHub.
• Para garantizar que despliegas GitHub Apps en los ambientes de desarrollo y de producción utilizando la misma configuración.
• Para rastrear las revisiones hechas en la configuración de una GitHub App.

Implementar el flujo del Manifiesto de una GitHub App

El flujo de manifiesto de aplicación de GitHub usa un proceso de protocolo de enlace similar al flujo de OAuth. El flujo usa un manifiesto para registrar una aplicación de GitHub y recibe un valor temporal code que se usa para recuperar la clave privada de la aplicación, el secreto de webhook y el identificador.

Sigue estos pasos par aimplementar el flujo del Manifiesto de la GitHub App:

1. Puedes redirigir a los usuarios a GitHub para registrar una nueva aplicación de GitHub.
2. GitHub redirige a las personas de vuelta a tu sitio.
3. Intercambias el código temporal para recuperar la configuración de la app.

1. Puedes redirigir a los usuarios a GitHub para registrar una nueva aplicación de GitHub.

Para redirigir a los usuarios al registro de una nueva aplicación de GitHub, proporciona un vínculo para que hagan clic en él y envíen una solicitud POST a https://github.com/settings/apps/new en el caso de una cuenta personal o a https://github.com/organizations/ORGANIZATION/settings/apps/new si se trata de una cuenta de la organización, reemplazando ORGANIZATION por el nombre de la cuenta de la organización donde se creará la aplicación.

Debes incluir los parámetros del manifiesto de aplicación de GitHub como una cadena codificada en JSON en un parámetro denominado manifest. También puedes incluir un parámetro state para mayor seguridad.

A la persona que registra la aplicación se le redirigirá a una página de GitHub con un campo de entrada donde puede editar el nombre de la aplicación que incluyó en el parámetro manifest. Si no incluyes un valor name en el elemento manifest, la persona puede establecer su propio nombre para la aplicación en este campo.

Parámetros del Manifiesto de la GitHub App

Nombre	Escribir	Descripción
name	string	El nombre de la GitHub App.
url	string	Obligatorio. Página principal de la GitHub App.
hook_attributes	object	Configuración del webhook de la GitHub App.
redirect_url	string	Dirección URL completa a la cual redireccionar después de que un usuario inicie el registro de una GitHub App desde un manifiesto.
callback_urls	array of strings	Una URL completa a la cual redirigir cuando alguien autorice una instalación. Puedes proporcionar hasta 10 URL de rellamado.
setup_url	string	Dirección URL completa a la que redirigir a los usuarios después de que instalen la GitHub App si se requiere una configuración adicional.
description	string	Una descripción de la GitHub App.
public	boolean	Defínala como true cuando la GitHub App esté disponible para el público o en false cuando solo puede acceder a ella el propietario de la aplicación.
default_events	array	Lista de eventos a los que se suscribe la GitHub App.
default_permissions	object	Conjunto de permisos necesarios para la aplicación de GitHub. El formato del objeto usa el nombre de permiso para la clave (por ejemplo, issues) y el tipo de acceso para el valor (por ejemplo, write). Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».
request_oauth_on_install	boolean	Establécelo en true para solicitar al usuario que autorice la GitHub App después de que se instale la GitHub App.
setup_on_update	boolean	Establécelo en true para redirigir a los usuarios a setup_url después de que actualicen la instalación de la GitHub App.

El objeto hook_attributes tiene las claves siguientes.

Nombre	Escribir	Descripción
url	string	Obligatorio. La dirección URL del servidor que va a recibir las solicitudes POST del webhook.
active	boolean	Entrega detalles del evento cuando se activa este gancho y su valor predeterminado es "true".

Parámetros

Nombre	Escribir	Descripción
state	string	Una secuencia aleatoria indescifrable. Se utiliza para protegerte contra los ataques de falsificación de solicitudes entre sitios.

Ejemplos

En este ejemplo se usa un formulario de una página web con un botón que desencadena la solicitud POST para una cuenta personal:

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

En este ejemplo se usa un formulario de una página web con un botón que desencadena la solicitud POST de una cuenta de organización. Reemplaza ORGANIZATION por el nombre de la cuenta de organización donde quieres registrar la aplicación.

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub redirige a las personas de nuevo a tu sitio.

Cuando la persona hace clic en Crear aplicación de GitHub, GitHub la redirige de nuevo a redirect_url con un elemento temporal code en un parámetro de código. Por ejemplo:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

Si proporcionaste un parámetro state, también verás ese parámetro en redirect_url. Por ejemplo:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. Se intercambia el código temporal para recuperar la configuración de la aplicación.

Para completar el protocolo de enlace, envía el elemento temporal code de una solicitud POST al punto de conexión. Consulta Creación de una aplicación de GitHub desde un manifiesto. La respuesta incluirá los valores de id (identificador de aplicación de GitHub), pem (clave privada) y webhook_secret. GitHub crea un secreto de webhook para la app de forma automática. Puedes almacenar estos valores en variables de ambiente dentro del servidor de la app. Por ejemplo, si la aplicación usa dotenv para almacenar variables de entorno, almacenarías las variables en el archivo .env de la aplicación.

Tienes solo una hora para completar este paso en el flujo del Manifiesto de la GitHub App.

POST /app-manifests/{code}/conversions

Para más información sobre la respuesta del punto de conexión, consulta Creación de una aplicación de GitHub a partir de un manifiesto.

Cuando se complete el último paso del flujo del manifiesto, la persona que ha registrado la aplicación desde el flujo será el propietario de una aplicación de GitHub registrada que podrá instalar en cualquiera de sus repositorios personales. En cualquier momento podrán elegir extender la app utilizando las API de GitHub, transferir la propiedad a alguien más, o borrarla.

Utilizar el Probot par aimplementar el flujo del Manifiesto de la GitHub App

Probot es un marco creado con Node.js que realiza muchas de las tareas que necesitan todas las aplicaciones de GitHub, como validar webhooks y realizar la autenticación. Probot implementa el flujo de manifiesto de aplicación de GitHub, lo que facilita la creación y el uso compartido de diseños de referencia de aplicaciones de GitHub con la comunidad de GitHub.

Para crear una App de Probot que puedas compartir, sigue estos pasos:

1. Genere una nueva aplicación de GitHub.
2. Abra el proyecto que ha creado y personalice la configuración en el archivo app.yml. Probot usa la configuración de app.yml como parámetros de manifiesto de aplicación de GitHub.
3. Agrega el código personalizado de tu aplicación.
4. Ejecuta la aplicación de GitHub localmente o bien hospédala en el lugar que prefieras. Al desplazarte a la dirección URL de la aplicación hospedada, encontrarás una página web con el botón Registrar aplicación de GitHub en el que los usuarios pueden hacer clic para crear una aplicación preconfigurada.

Con dotenv, Probot crea un archivo .env y establece las variables de entorno APP_ID, PRIVATE_KEY y WEBHOOK_SECRET con los valores recuperados de la configuración de la aplicación.

Hospedar tu app con Glitch

Puedes ver una aplicación Probot de ejemplo que usa Glitch para hospedar y compartir la aplicación. En el ejemplo se usa Checks API y se seleccionan los eventos y permisos necesarios de Checks API en el archivo app.yml. Glitch es una herramienta que te permite "Remezclar tus propias apps". El remezclar una app crea una copia de la app que Glitch hospeda y despliega. Consulta "Acerca de Glitch" para información sobre la remezcla de aplicaciones Glitch.