Acerca de los parámetros URL para crear aplicaciones GitHub App
Puedes usar parámetros URL para preseleccionar las opciones de configuración de una nueva 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 aplicación, 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 obtener más información, vea «Crear una GitHub App a partir de 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 crear una aplicación en una cuenta personal, agrega parámetros de dirección URL a:
https://github.com/settings/apps/new. - Para crear una aplicación en una cuenta de organización, agrega parámetros de dirección URL a:
https://github.com/organizations/ORGANIZATION/settings/apps/new. ReemplazaORGANIZATIONpor el nombre de la organización donde quieres que el cliente cree la aplicación.
En la página de registro de la aplicación, la persona que crea la aplicación puede editar los valores preseleccionados antes de distribuir la aplicación. Si no incluyes los parámetros para los valores requeridos (como name) en la cadena de consulta de la URL, el creador de la aplicación necesitará introducir un valor antes de distribuirla.
Por ejemplo, la siguiente dirección URL crea 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:
https://github.com/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 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 | Tipo | Descripción |
|---|---|---|
name | string | El nombre de la GitHub App. Pónle un nombre claro y breve a tu app. Tu app no puede tener el mismo nombre de ningún usuario existente en GitHub, a menos de que sea tu propio nombre de usuario u organización. 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 obtener más información, vea «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. |
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. |
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 necesita administrar varios archivos, consulte 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 GitHub App. Para obtener más información sobre los posibles permisos que puedes seleccionar para la aplicación y los puntos de conexión a los que la aplicación puede acceder con cada permiso, consulta "Permisos que requieren las Github Apps". 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 crea 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".