Acerca de los parámetros de dirección URL para registrar GitHub Apps
Puedes usar parámetros URL para preseleccionar las opciones de configuración de un nuevo registro de GitHub App y compartir un vínculo personalizado con otras personas. El vínculo llevará a los usuarios a una página de registro de GitHub App, donde la configuración de la aplicación se rellenará previamente según los parámetros URL que incluiste en la dirección URL.
Este enfoque es útil para los integradores que desean que los clientes configuren una aplicación en su cuenta personal u organización con determinadas especificaciones, o para los clientes que usanGitHub Enterprise Server que no pueden instalar aplicaciones desde GitHub Marketplace.
Como alternativa, puedes crear un manifiesto GitHub App. Para más información, consulta Registro de una aplicación de GitHub desde un manifiesto.
Creación de una dirección URL de configuración personalizada con parámetros de consulta
Para crear una dirección URL de configuración personalizada para una aplicación GitHub App en una cuenta personal o de organización, agrega parámetros de consulta después de las siguientes direcciones URL base.
- Para registrar una aplicación en una cuenta personal, agrega parámetros URL a
http(s)://HOSTNAME/settings/apps/new. - Para registrar una aplicación en una cuenta profesional, agrega parámetros URL a
http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new. ReemplazaORGANIZATIONpor el nombre de la organización donde quieres que el cliente registre la aplicación.
En la página de registro de la aplicación, la persona que registra la aplicación puede editar los valores preseleccionados antes de distribuirla. Si no incluyes los parámetros para los valores requeridos (como name) en la cadena de consulta de URL, la persona que registra la aplicación deberá introducir un valor antes de registrarla.
Por ejemplo, la siguiente dirección URL registra una nueva aplicación pública denominada octocat-github-app en una cuenta personal. Con parámetros de consulta, la dirección URL preconfigura una descripción y una dirección URL de devolución de llamada. También selecciona permisos de lectura y escritura para checks, activa webhooks con el parámetro webhook_active, se suscribe a los eventos de webhook check_run y check_suite y selecciona la opción para solicitar la autorización del usuario (OAuth) durante la instalación:
http(s)://HOSTNAME/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite
Parámetros de configuración de una GitHub App
Puedes usar los parámetros de consulta siguientes para seleccionar una configuración específica para el registro de GitHub App. Por ejemplo, para asignar un nombre a la aplicación "octocat-github-app", la cadena de consulta incluiría name=octocat-github-app.
| Nombre de parámetro | Type | Descripción |
|---|---|---|
name | string | El nombre de la GitHub App. Pónle un nombre claro y breve a tu app. Tu aplicación no puede tener el mismo nombre que el de un usuario existente de GitHub, a menos de que dicho nombre sea el de tu organización o usuario. Una versión simplificada del nombre de tu aplicación se mostrará en la interface de usuario cuando tu integración tome alguna acción. |
description | string | Una descripción de la GitHub App. |
url | string | La URL complea de la página principal del sitio web de tu GitHub App. |
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. Estas direcciones URL se usan si la aplicación necesita generar un token de acceso de usuario. Por ejemplo, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Para más información, consulta Acerca de la dirección URL de devolución de llamada de autorización de usuario. |
request_oauth_on_install | boolean | Si su aplicación autoriza a los usuarios mediante el flujo de OAuth, puede configurar esta opción como true para permitir que las personas autoricen la aplicación cuando la instalen, lo que le permite ahorrarse un paso. Si selecciona esta opción, la setup_url dejará de estar disponible y se redirigirá a los usuarios a su callback_url después de instalar la aplicación. |
setup_url | string | La URL completa a la cual se redirigirá después de que instalen la GitHub App si ésta requiere de alguna configuración adicional después de su instalación. Para más información, consulta Acerca de la URL de configuración. |
setup_on_update | boolean | Defínala como true para redirigir a los usuarios a la dirección URL de configuración cuando las instalaciones se actualicen, por ejemplo, después de que se agreguen o eliminen repositorios. |
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. Este parámetro no se aplica a las aplicaciones propiedad de empresas. |
webhook_active | boolean | Establécelo en true para habilitar el webhook. El webhook está deshabilitado de forma predeterminada. |
webhook_url | string | La URL completa a la cual quisieras enviar cargas útiles de eventos de webhook. |
events | array of strings | Eventos de webhook. Algunos eventos de webhook requieren los permisos de read o write de un recurso para poder seleccionar el evento al registrar una nueva GitHub App. Para obtener más información, consulta la sección Eventos de webhook de GitHub App. Puedes seleccionar eventos múltiples en una secuencia de consulta. Por ejemplo, events[]=public&events[]=label. |
single_file_name | string | Este es un permiso con alcance corto que permite a la app acceder a un solo archivo en cualquier repositorio. Al establecer el permiso de single_file en read o write, este campo proporciona la ruta de acceso al único archivo que administrará su GitHub App. Si necesitas administrar varios archivos, consulta single_file_paths a continuación. |
single_file_paths | array of strings | Esto permite a la app acceder hasta a 10 archivos especificos en un repositorio. Al establecer el permiso single_file en read o write, esta matriz puede almacenar las rutas de acceso de hasta diez archivos que administrará su GitHub App. Todos estos archivos reciben los mismos permisos establecidos por single_file, y no tienen permisos individuales independientes. Cuando se configuran dos o más archivos, la API devuelve multiple_single_files=true; de lo contrario, devolverá multiple_single_files=false. |
Permisos de la GitHub App
Puedes usar parámetros de consulta para seleccionar los permisos para el registro de GitHub App. Para el parámetro de consulta de dirección URL, usa el nombre del permiso como nombre del parámetro de consulta y establece el valor de la consulta en uno de los valores posibles para ese conjunto de permisos.
Por ejemplo, para seleccionar permisos de tipo "Lectura y escritura" en la interfaz de usuario para contents, la cadena de consulta incluirá contents=write. Para seleccionar permisos de tipo "Solo lectura" en la interfaz de usuario para blocking, la cadena de consulta incluirá blocking=read. Para seleccionar "Sin acceso" en la interfaz de usuario para checks, la cadena de consulta no incluirá el permiso checks.
Para más información sobre los permisos y GitHub Apps, consulta Elección de permisos para una aplicación de GitHub.
Eventos de webhook de GitHub App
Puedes usar parámetros de consulta para habilitar el webhook GitHub App, designar una dirección URL de webhook y suscribir la aplicación para recibir cargas de webhook para eventos específicos.
Para habilitar el webhook de GitHub App, usa webhook_active=true en la cadena de consulta. Para designar una dirección URL completa a la que deseas enviar cargas de eventos de webhook, usa webhook_url en la cadena de consulta. Para suscribir la aplicación a eventos de carga de webhook específicos, usa events[] como nombre del parámetro de consulta y establece el valor de consulta en el nombre del evento de webhook. Para obtener más información sobre los posibles eventos de webhook y los permisos de GitHub App necesarios para suscribirse a cada evento, consulta Eventos y cargas de webhook.
Por ejemplo, para suscribirse a un GitHub App para recibir cargas de webhook para la actividad relacionada con los comentarios de confirmación, la cadena de consulta incluiría &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Ten en cuenta que el evento de webhook commit_comment requiere que GitHub App tenga al menos acceso de nivel de lectura para el permiso del repositorio "Contenido". Por lo tanto, la cadena de consulta también debe incluir un parámetro para establecer el permiso contents en read o write. Para obtener más información, consulta Permisos de aplicación de GitHub.
No se pueden usar parámetros de consulta para establecer el valor de un secreto de webhook. Si una aplicación requiere un secreto para proteger su webhook, la persona que registra la aplicación debe establecer el valor del secreto en la interfaz de usuario de GitHub.
Para más información sobre los webhooks y GitHub Apps, consulta Uso de webhooks con aplicaciones de GitHub.