Registro de una aplicación de GitHub desde un manifiesto

Acerca de los manifiestos de GitHub App

Cuando alguien crea una GitHub App 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 GitHub App y genera el secreto del webhook, la llave privada (archivo PEM), el secreto de cliente y el identificador de GitHub App. 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 GitHub App o ver una implementación de ejemplo. Consulta Uso de Probot para implementar el flujo de manifiesto de GitHub App para más información.

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

• Para ayudar a los miembros nuevos del equipo a que se familiaricen rápidamente con el desarrollo de GitHub Apps.
• Permitir que otros extiendan una GitHub App usando las API de GitHub sin requerir que configuren una aplicación.
• Crear diseños de referencia de GitHub App para 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.
• Haz un seguimiento de las revisiones a una configuración de la GitHub App

Implementación del flujo de manifiesto de GitHub App

El flujo de manifiesto de GitHub App usa un proceso de protocolo de enlace similar al flujo de OAuth. El flujo usa un manifiesto para registrar una GitHub App 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. Redirige a los usuarios a GitHub para registrar una nueva GitHub App.
2. La GitHub redirige a los usuarios de nuevo a tu sitio.
3. Intercambias el código temporal para recuperar la configuración de la app.

1. Redirige a los usuarios a GitHub para registrar una nueva GitHub App

Para redirigir a los usuarios al registro de una nueva GitHub App, 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 GitHub App 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 de manifiestos de 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	El conjunto de permisos requeridos por la GitHub App. 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 más información, consulta 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. La GitHub redirige a los usuarios de nuevo a tu sitio

Cuando la persona hace clic en Crear GitHub App, GitHub la redirige de nuevo a redirect_url con un code temporal 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 GitHub App desde un manifiesto. La respuesta incluirá los siguientes datos: id (ID de GitHub App), pem (clave privada) y webhook_secret. GitHub crea automáticamente una clave secreta de webhook para la aplicación. 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 GitHub App 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 GitHub App 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.

Uso de Probot para implementar el flujo de manifiesto de GitHub App

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

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

1. Generar una nueva GitHub App.
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 GitHub App.
3. Agrega el código personalizado de tu aplicación.
4. Ejecute la GitHub App localmente o hospédala allí donde quieras. Al desplazarte a la dirección URL de la aplicación hospedada, encontrarás una página web con el botón Registrar GitHub App 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.