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 el uso de Probot para implementar el flujo de manifiesto de GitHub App para obtener 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 utiliza un proceso de enlace similar al de OAuth. El flujo usa un manifiesto para registrar una GitHub App y recibe un valor temporal que se utiliza para recuperar la clave privada de la aplicación, el secreto de webhook y el ID.

Sigue estos pasos para implementar 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 enlace en el que puedan hacer clic para enviar una solicitud: una para una cuenta personal y otra para una cuenta de organización, reemplazando con el nombre de la cuenta de la organización donde se registrará la aplicación.

Debes incluir los parámetros del manifiesto de GitHub App como una cadena codificada en JSON en un parámetro denominado . También puedes incluir un parámetro 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 . Si no incluyes un en el , pueden establecer su propio nombre para la aplicación en este campo.

Parámetros de manifiestos de GitHub App

Nombre	Tipo	Descripción
name	string	El nombre de la GitHub App.
url	string	Obligatorio. La página principal de la aplicación 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 proveer hasta 10 URL de retorno de llamada.
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 cuando la GitHub App esté disponible para el público o en 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, ) y el tipo de acceso para el valor (por ejemplo, ). Para más información, consulta AUTOTITLE. A fin de ver la lista de permisos disponibles para su uso y sus nombres con parámetros, consulta AUTOTITLE.
request_oauth_on_install	boolean	Establécelo para solicitar al usuario que autorice la GitHub App, después de que se instale la GitHub App.
setup_on_update	boolean	Configúralo para redirigir a los usuarios después de que actualicen la instalación de la GitHub App.

El objeto tiene las claves siguientes.

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

Parámetros

Nombre	Tipo	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 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 de una cuenta de organización. Reemplaza 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 GitHub App, GitHub la redirige de nuevo a con un temporal en un parámetro de código. Por ejemplo:

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

Si proporcionaste un parámetro , también verás ese parámetro en . 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 en una solicitud al punto de conexión de creación de una GitHub App desde un manifiesto. La respuesta incluirá los siguientes datos: (ID de GitHub App), (clave privada) y . 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 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, el usuario que registra la aplicación desde el flujo será el propietario de una GitHub App registrada que puede instalar en cualquiera de sus cuentas. 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, facilitando crear y compartir diseños de referencia de GitHub App con la comunidad de GitHub.

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

1. Crear una nueva GitHub App.
2. Abra el proyecto que ha creado y personalice la configuración en el archivo . Probot utiliza la configuración en como los parámetros del 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 y establece las variables de entorno , y con los valores recuperados de la configuración de la aplicación.

Alojar tu aplicación 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 . 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.