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.
Note
Debes completar los tres pasos del flujo de manifiesto de GitHub App en un plazo de una hora.
Sigue estos pasos par aimplementar el flujo del Manifiesto de la GitHub App:
- Redirige a los usuarios a GitHub para registrar una nueva GitHub App.
- La GitHub redirige a los usuarios de nuevo a tu sitio.
- 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 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. 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.
Nota: Este punto de conexión es de velocidad limitada. Consulta Límites de velocidad para información sobre cómo obtener el estado del límite de velocidad actual.
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:
- Generar una nueva GitHub App.
- Abra el proyecto que ha creado y personalice la configuración en el archivo
app.yml
. Probot usa la configuración deapp.yml
como parámetros de manifiesto de GitHub App. - Agrega el código personalizado de tu aplicación.
- 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.