Acerca de los parámetros de dirección URL para el registro GitHub Apps
Puede usar parámetros de dirección URL para preseleccionar las opciones de configuración de un nuevo GitHub App registro y compartir un vínculo personalizado con otras personas. El enlace llevará a las personas a una página de registro GitHub App, donde la configuración de la aplicación aparecerá rellenada previamente según los parámetros de la URL que haya incluido en la URL.
Este enfoque es útil para los integradores que quieren que los clientes configuren una aplicación en su cuenta personal u organización con determinadas especificaciones, o para los clientes que usan GitHub Enterprise Server quiénes no pueden instalar aplicaciones desde .GitHub Marketplace
Como alternativa, puede crear un GitHub App manifiesto. 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 GitHub App cuenta personal o de organización, agregue 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. - Para registrar una aplicación en una cuenta de empresa, agrega parámetros de URL a
http(s)://HOSTNAME/enterprises/ENTERPRISE/settings/apps/new. Reemplace porENTERPRISEel nombre de la empresa donde desea 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
GitHub App parámetros de configuración
Puede usar los siguientes parámetros de consulta para seleccionar una configuración específica para el GitHub App registro. 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 | Tipo | Descripción |
|---|---|---|
name | string | El nombre del GitHub App. Pónle un nombre claro y breve a tu app. La aplicación no puede tener el mismo nombre que un usuario existente GitHub , a menos que sea su propio usuario o nombre de organización. Una versión simplificada del nombre de tu aplicación se mostrará en la interfaz de usuario cuando tu integración realice una acción. |
description | string | Descripción de GitHub App. |
url | string | La URL completa 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 proveer hasta 10 URL de retorno de llamada. Estas direcciones URL se usan si la aplicación necesita generar un token de acceso de usuario. Por ejemplo: callback_urls[]=https:/. Para más información, consulta Acerca de la dirección URL de devolución de llamada de autorización de usuario. |
request_oauth_ | 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 dirección URL completa a la que se redirigirá después de que alguien instale GitHub App si la aplicación requiere una instalación adicional después de la 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 | 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. 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 quieres enviar los contenidos de eventos de webhook. |
events | array of strings | Eventos de webhook. Algunos eventos de webhook requieren read o write permisos para un recurso antes de poder seleccionar el evento al registrar un nuevo GitHub App. Para obtener más información, consulte la sección GitHub Appeventos de webhook. 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 single_file permiso en read o write, este campo proporciona la ruta de acceso al único archivo que GitHub App administrará. 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. Cuando establezca el permiso single_file en read o write, esta matriz puede almacenar las rutas de hasta diez archivos que gestionará 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_; de lo contrario, devolverá multiple_single_. |
GitHub App permisos
Puede usar parámetros de consulta para seleccionar los permisos para el GitHub App registro. 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ía el permiso checks.
Para obtener más información sobre los permisos y GitHub Apps, vea 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.
GitHub App eventos del webhook
Puede usar parámetros de consulta para habilitar el GitHub App webhook, designar una dirección URL de webhook y suscribir la aplicación para recibir cargas de webhook para eventos específicos.
Para habilitar el GitHub App webhook, use 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 GitHub App permisos necesarios para suscribirse a cada evento, consulte Eventos y cargas de webhook.
Por ejemplo, para suscribirse GitHub App a 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. Tenga en cuenta que el evento de webhook commit_comment requiere que GitHub App tenga al menos acceso de solo lectura al permiso de 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, consulte GitHub Permisos de aplicación.
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 GitHub interfaz de usuario.
Para obtener más información sobre los webhooks y GitHub Apps, vea Uso de webhooks con aplicaciones de GitHub.