Acerca de los Manifiestos de las GitHub Apps
Cuando alguien crea una GitHub App desde un manifiesto, únicamente necesitan seguir una URL y nombrar a la app. 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 recupera el secreto del webhook, llave privada (archivo PEM), e ID de la GitHub App. Quien sea que cree la app desde el manifiesto será el propietario de la misma y podrá elegir editar los ajustes de la configuración de seguridad de la app, eliminarlos, o transferirlos a otra persona en GitHub.
Puedes utilizar al Probot para comenzar a utilizar los Manifiestos de las GitHub Apps o ver un ejemplo de implementación. Consulta la sección "Utilizar al Probot para implementar el flujo del Manifiesto de las GitHub Apps" para obtener más información.
Aquí te mostramos algunos escenarios en donde podrías utilizar los Manifiestos de las GitHub Apps para crear apps 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 del Manifiesto de una GitHub App utiliza un proceso de intercambio similar al del flujo de OAuth. El flujo utiliza un manifiesto para registrar una GitHub App y recibe un code temporal que se utiliza para recuperar la llave privada, webhoo, secreto, e ID de la misma.
Nota: Tienes solo una hora para completar los tres pasos del flujo del Manifiesto de la GitHub App.
Sigue estos pasos par aimplementar el flujo del Manifiesto de la GitHub App:
- Redireccionas a las personas a GitHub para crear una GitHub App Nueva.
- GitHub redirige a las personas de vuelta a tu sitio.
- Intercambias el código temporal para recuperar la configuración de la app.
1. Redireccionas a las personas a GitHub para crear una GitHub App Nueva
Para redireccionar a las personas a crear una GitHub App nueva, proporciona un enlace para que ellos den clic y envíen una solicitud de POST a https://github.com/settings/apps/new para una cuenta de usuario o a https://github.com/organizations/ORGANIZATION/settings/apps/new para una cuenta de organización, reemplazando ORGANIZATION con el nombre de la cuenta de organización en donde se creará la app.
Debes incluir los Parámetros del Manifiesto de la GitHub App como una secuencia cifrada con JSON en un parámetro que se llame manifest. También puedes incluir un parámetro de state para agregar seguridad adicional.
Se redirigirá al creador de la app a una página de GitHub en donde encontrará un campo de entrada y ahí podrá editar el nombre de la app que incluiste en el parámetro de manifest. Si no incluyes un name en el manifest, podrán configurar un nombre de su elección para la app en este campo.
Parámetros del Manifiesto de la GitHub App
| Nombre | Tipo | Descripción |
|---|---|---|
name (nombre) | secuencia | El nombre dela GitHub App. |
url | secuencia | Requerido. La página principal de tu GitHub App. |
hook_attributes | objeto | La configuración del webhook de la GitHub App. |
redirect_url | secuencia | La URL completa a la cual se redireccionará a la persona después de que instale la GitHub App. |
descripción | secuencia | Una descripción de la GitHub App. |
public | boolean | Configúralo como true cuando tu GitHub App esté disponible al público o como false si solo puede acceder el propietario de la misma. |
default_events | array | La lista de eventos a la cual se suscribe la GitHub App. |
default_permissions | objeto | El conjunto de permisos que requiere la GitHub App. El formato del objeto utiliza el nombre del permiso para la clave (por ejemplo, issues) y el tipo de acceso para el valor (por ejemplo, write). |
El objeto hook_attributes tiene la siguiente clave:
| Nombre | Tipo | Descripción |
|---|---|---|
url | secuencia | Requerido. La URL del servidor que recibirá las solicitudes de POST 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 | secuencia | Una secuencia aleatoria indescifrable. Se utiliza para protegerte contra los ataques de falsificación de solicitudes entre sitios. |
Ejemplos
Este ejemplo utiliza un formato en una página web con un botón que activa la solicitud de tipo POST para una cuenta de usuario:
<form action="https://github.com/settings/apps/new?state=abc123" method="post">
Create 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/callback",
"public": true,
"default_permissions": {
"issues": "write",
"checks": "write"
},
"default_events": [
"issues",
"issue_comment",
"check_suite",
"check_run"
]
})
</script>
Este ejemplo utiliza un formato en una página web con un botón que activa la solicitud de tipo POST para una cuenta de organización. Reemplaza a ORGANIZATION con el nombre de la cuenta de organización en donde quieras crear la app.
<form action="https://github.com/organizations/<em>ORGANIZATION</em>/settings/apps/new?state=abc123" method="post">
Create 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/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 vuelta a tu sitio
Cuando la persona dé clic en Crear GitHub App, Github lo redirigirá a la redirect_url con un code temporal en un parámetro de código. Por ejemplo:
https://example.com/callback?code=a180b1a3d263c81bc6441d7b990bae27d4c10679
Si proporcionaste un parámetro de state, también verás este parámetro en la redirect_url. Por ejemplo:
https://example.com/callback?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123
3. Intercambias el código temporal para recuperar la configuración de la app
Para completar el intercambio, envía el code temporal en una solicitud de tipo POST a la terminal Crear una Github App a partir de un manifiesto. La respuesta incluirá la id (GitHub App ID), la pem (llave privada), y el 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 tu app utiliza dotenv para almacenar las variables de ambiente, almacenarías las variables en el archivo .env de tu app.
Tienes solo una hora para completar este paso en el flujo del Manifiesto de la GitHub App.
Nota: Esta terminal tiene un límite de tasa. Consulta la sección Límites de tasa para aprender cómo obtener tu estado actual de límite de tasa.
POST /app-manifests/:code/conversions
Para obtener más información acerca de la respuesta de la terminal, consulta la sección Crear una GitHub App desde un manifiesto.
Cuando se complete el último paso del flujo del manifiesto, la persona que cree la app 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.
Utilizar el Probot par aimplementar el flujo del Manifiesto de la GitHub App
El Probot es un marco de trabajo que se creó con Node.js y que realiza muchas de las tareas que todas las GitHub Apps requieren, como el validar webhooks y llevar a cabo la autenticación. El Probot implementa el flujo del manifiesto de las GitHub Apps, lo cual facilita el crear y compartir los diseños de referencia de las GitHub Apps con la comunidad de GtiHub.
Para crear una App de Probot que puedas compartir, sigue estos pasos:
- Genera una GitHub App Nueva.
- Abre el proyecto que creaste y personaliza la configuración en el archivo
app.yml. El Probot utiliza la configuración enapp.ymlcomo los parámetros del manifiesto dela GitHub App. - Agrega el código personalizado de tu aplicación.
- Ejecuta la GitHub App localmente u hospédala en donde quieras. Cuando navegues a la URL de la app hospedada, encontrarás una página web con un botón de Registrar GitHub App en el que as personas podrán dar clic para crear una app preconfigurada. La siguiente página web es la implementación del Probot para el paso 1 en el flujo del Manifiesto de la GitHub App:
Al utilizar dotenv, el Probot crea un archivo de tipo .env y configura las variables de ambiente para la APP_ID, PRIVATE_KEY, y el WEBHOOK_SECRET con los valores que recupera de la configuración de la app.
Hospedar tu app con Glitch
Puedes ver un ejemplo de una App de Probot de muestra que utiliza Glitch para hospedar y compartir la app. El ejemplo utiliza la API de verificaciones y selecciona los eventos necesarios de la misma y los permisos 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 la sección "Acerca de Glitch" para aprender sobre cómo remezclar las apps de Glitch.