Registro de una aplicación de GitHub desde un manifiesto

Acerca de GitHub App Manifiestos

Nota:

GitHub App Los manifiestos no están disponibles para entidades propiedad de la empresa GitHub Apps.

Cuando alguien registra un GitHub App desde un manifiesto, solo necesitan seguir una dirección 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 de manifiesto crea el GitHub App registro y genera el secreto de webhook de la aplicación, la clave privada (archivo PEM), el secreto de cliente y el ID GitHub App. La persona que crea el GitHub App registro a partir del manifiesto poseerá el GitHub App registro y puede elegir editar la configuración del registro, eliminarlo o transferirlo a otra persona en GitHub.

Puede usar Probot para empezar a trabajar con GitHub App manifiestos o ver una implementación de ejemplo. Consulte Uso de Probot para implementar el flujo de GitHub App manifiesto para obtener más información.

Estos son algunos escenarios en los que puede usar GitHub App manifiestos para registrar aplicaciones preconfiguradas:

Ayude a los nuevos miembros del equipo a ponerse al día rápidamente al desarrollar GitHub Apps.
Permitir que otros usuarios extiendan un GitHub App mediante las GitHub API sin necesidad de configurar una aplicación.
Cree GitHub App diseños de referencia para compartirlos con la GitHub comunidad.
Asegúrese de implementar GitHub Apps en entornos de desarrollo y producción con la misma configuración.
Realice un seguimiento de las revisiones de una GitHub App configuración.

Implementación del flujo del GitHub App Manifiesto

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

Nota:

Debe completar los tres pasos del GitHub App flujo del manifiesto en una hora.

Siga estos pasos para implementar el flujo del GitHub App manifiesto:

Redirigir a las personas a GitHub para registrar un nuevo GitHub App.

       GitHub redirige a las personas de nuevo a su sitio.

Intercambias el código temporal para recuperar la configuración de la app.

1. Redirige a las personas a GitHub para registrar un nuevo GitHub App

Para redirigir a las personas a registrar un nuevo GitHub App, proporcione un vínculo para que haga clic en él y envíe una POST solicitud a https://github.com/settings/apps/new para una cuenta personal o https://github.com/organizations/ORGANIZATION/settings/apps/new para una cuenta de organización, reemplazando ORGANIZATION por el nombre de la cuenta de la organización donde se registrará la aplicación.

Debe incluir los GitHub App parámetros manifest como una cadena codificada en JSON en un parámetro denominado manifest. También puedes incluir un parámetro state para mayor seguridad.

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

          GitHub App Parámetros de manifiesto

Nombre	Tipo	Descripción
`name`	`string`	El nombre del GitHub App.
`url`	`string`

          **Obligatorio.** La página principal de su GitHub App.

hook_attributes | object | Configuración del webhook de GitHub App. redirect_url | string | Dirección URL completa a la que se redirigirá después de que un usuario inicie el registro de un 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 | Una URL completa para redirigir a los usuarios después de instalar tu GitHub App si se requiere configuración adicional. description | string | Descripción de GitHub App. public | boolean | Establézcalo en true cuando GitHub App esté disponible para el público o false cuando solo sea accesible para el propietario de la aplicación. default_events | array | Lista de eventos a los que GitHub App se suscribe. default_permissions | object | Conjunto de permisos necesarios por el 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. A fin de ver la lista de permisos disponibles para su uso y sus nombres con parámetros, consulta Administración de tokens de acceso personal. request_oauth_on_install | boolean | Establézcalo en true para solicitar al usuario que autorice GitHub App, después de instalar GitHub App. setup_on_update | boolean | Establézcalo en true para redirigir a los usuarios a setup_url después de actualizar la GitHub App instalación.

El objeto hook_attributes tiene las claves siguientes.

Nombre	Tipo	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	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 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 su sitio

Cuando la persona hace clic en Crear GitHub App, GitHub redirige de nuevo a la 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íe el elemento temporal code en una POST petición al punto de conexión Crear un GitHub App desde un manifiesto. La respuesta incluirá el id (GitHub App ID), pem (clave privada) y webhook_secret. GitHub crea automáticamente un secreto 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.

Debe completar este paso del GitHub App flujo de manifiesto en un plazo de una hora.

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 obtener más información sobre la respuesta del punto de conexión, consulte Crear a GitHub App partir de un manifiesto.

Cuando se complete el paso final del flujo de manifiesto, la persona que registra la aplicación desde el flujo será el propietario de un GitHub App registrado que se puede instalar en cualquiera de sus cuentas. Pueden optar por ampliar la aplicación mediante las GitHub API, transferir la propiedad a otra persona o eliminarla en cualquier momento.

Uso de Probot para implementar el flujo de GitHub App Manifesto

          [Probot](https://probot.github.io/) es un marco creado con [Node.js](https://nodejs.org/) que realiza muchas de las tareas necesarias para todos GitHub Apps, como validar webhooks y realizar la autenticación. Probot implementa el flujo de [GitHub App manifiesto](#implementing-the-github-app-manifest-flow), lo que facilita la creación y compartición GitHub App de diseños de referencia con la comunidad GitHub.

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

       [Genere un nuevo GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).

Abra el proyecto que ha creado y personalice la configuración en el archivo app.yml. Probot usa la configuración en app.yml como los GitHub App parámetros del manifiesto.
Agrega el código personalizado de tu aplicación.

       [Ejecute GitHub App localmente](https://probot.github.io/docs/development/#running-the-app-locally) o hospédelo donde desee. Al navegar a la dirección URL de la aplicación hospedada, encontrará una página web con un botón **Registrar GitHub App** que los usuarios pueden hacer clic para registrar 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.

Registro de una aplicación de GitHub desde un manifiesto

En este artículo