Acerca de los parámetros de URL de las GitHub App
Puedes agregar parámetros de consulta a estas URL para preseleccionar la configuración de una GitHub App en una cuenta organizacional o personal:
- Cuenta personal:
http(s)://[hostname]/settings/apps/new - Cuenta de organización:
http(s)://[hostname]/organizations/:org/settings/apps/new
El creador de la app puede editar los valores preseleccionados desde la página de registro de la GitHub App antes de emitirla. Si no incluye los parámetros necesarios en la cadena de consulta de la URL, como el name, el creador de la aplicación necesitará introducir un valor antes de enviarla.
En el caso de las apps que requieren que un secreto asegure su webhook, la persona que crea la app debe configurar el valor de dicho secreto y no se debe hacer utilizando parámetros de consulta. Para obtener más información, consulte "Protección de los webhooks".
La siguiente dirección URL crea una nueva aplicación pública llamada octocat-github-app con una descripción preconfigurada y una dirección URL de devolución de llamada. Esta dirección URL también selecciona permisos de lectura y escritura para checks, se suscribe a los eventos de webhook check_run y check_suite 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&events[]=check_run&events[]=check_suite
La lista completa de parámetros de consulta, permisos y eventos disponibles se lista en las secciones siguientes.
Parámetros de configuración de una GitHub App
| Nombre | 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 URL se utilizan si tu app necesita identificar y autorizar solicitudes de usuario a servidor. Por ejemplo, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. |
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 | Defínala como false para deshabilitar el webhook. El webhook se encuentra habilitado predeterminadamente. |
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. Consulte la sección "Eventos de webhook de GitHub App para ver los eventos disponibles y los permisos necesarios. Puedes seleccionar eventos múltiples en una secuencia de consulta. Por ejemplo, events[]=public&events[]=label. |
domain | string | La URL de una referencia de contenido. |
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 seleccionar los permisos en una secuencia de consulta utilizando los nombres de permiso conforme en la siguiente tabla a manera de nombres de parámetro de consulta y usando el tipo de permiso como el valor de la consulta. Por ejemplo, para seleccionar permisos de Read & write en la interfaz de usuario para contents, la cadena de consulta incluirá &contents=write. Para seleccionar permisos de Read-only en la interfaz de usuario para blocking, la cadena de consulta incluirá &blocking=read. Para seleccionar no-access en la interfaz de usuario para checks, la cadena de consulta no incluirá el permiso checks.
| Permiso | Descripción |
|---|---|
administration | Otorga acceso a diversas terminales para la administración de organizaciones y repositorios. Puede ser none, read o write. |
checks | Concede acceso a la API de comprobaciones. Puede ser none, read o write. |
content_references | Concede acceso al punto de conexión "Crear datos adjuntos de contenido". Puede ser none, read o write. |
contents | Otorga acceso a diversas terminales que te permiten modificar el contenido de los repositorios. Puede ser de tipo none, read o write. |
deployments | Concede acceso a la API de implementaciones. Puede ser none, read o write. |
emails | Concede acceso a la API de correos electrónicos. Puede ser none, read o write. |
followers | Concede acceso a la API de seguidores. Puede ser de tipo none, read o write. |
gpg_keys | Concede acceso a la API de claves de GPG. Puede ser de tipo none, read o write. |
issues | Concede acceso a la API de incidencias. Puede ser de tipo none, read o write. |
keys | Concede acceso a la API de claves públicas. Puede ser de tipo none, read o write. |
members | Otorga acceso para administrar los miembros de una organización. Puede ser none, read o write. |
organization_hooks | Concede acceso a la API de webhooks de la organización. Puede ser de tipo none, read o write. |
organization_plan | Concede acceso para obtener información sobre el plan de una organización mediante el punto de conexión "Obtener una organización". Puede ser none o read. |
organization_projects | Concede acceso a la API de proyectos. Puede ser none, read, write o admin. |
pages | Concede acceso a la API de páginas. Puede ser de tipo none, read o write. |
plan | Concede acceso para obtener información sobre el plan de GitHub de un usuario mediante el punto de conexión "Obtener un usuario". Puede ser none o read. |
pull_requests | Otorga acceso a varias terminales de solicitud de extracción. Puede ser de tipo none, read o write. |
repository_hooks | Concede acceso a la API de webhooks del repositorio. Puede ser de tipo none, read o write. |
repository_projects | Concede acceso a la API de proyectos. Puede ser none, read, write o admin. |
secret_scanning_alerts | Concede acceso a la API de análisis de secretos. Puede ser none, read o write. |
security_events | Concede acceso a la API de análisis de código. Puede ser none, read o write. |
single_file | Concede acceso a la API de contenido. Puede ser de tipo none, read o write. |
starring | Concede acceso a la API de marcación con estrellas. Puede ser de tipo none, read o write. |
statuses | Concede acceso a la API de estados. Puede ser de tipo none, read o write. |
team_discussions | Concede acceso a la API de debates de equipos y la API de comentarios de debates de equipos. Puede ser de tipo none, read o write. |
vulnerability_alerts | Otorga acceso para recibir Dependabot alerts en un repositorio. Consulte "Acerca de Dependabot alerts" para obtener más información. Puede ser none o read. |
watching | Otorga acceso a la lista y cambia los repositorios a los que un usuario está suscrito. Puede ser de tipo none, read o write. |
Eventos de webhook de GitHub App
| Nombre del evento de webhook | Permiso necesario | Descripción |
|---|---|---|
check_run | checks | Ha ocurrido una actividad de ejecución de verificación. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "ejecuciones de comprobación". |
check_suite | checks | Ha ocurrido una actividad de suite de verificaciones. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, consulta la API REST de "conjuntos de comprobación". |
commit_comment | contents | Se creó un comentario de una confirmación. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "confirmación de comentarios". |
content_reference | content_references | Una nueva referencia de contenido es created. Se crea una referenci de contenido nueva cuando el cuerpo o el comentario de un informe de problemas o solicitud de extracción incluye un URL que empte con un dominio de referencia de contenido configurado. Para más información sobre las referencias de contenido y los datos adjuntos, vea "Uso de datos adjuntos de contenido". |
create | contents | Se crea una rama o etiqueta de Git. Para más información, vea la API REST de "base de datos de Git". |
delete | contents | Se borra una rama o etiqueta de Git. Para más información, vea la API REST de "base de datos de Git". |
deployment | deployments | Se crea un despliegue. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, consulta la API de REST de "implementación". |
deployment_status | deployments | Se crea un despliegue. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "implementaciones". |
fork | contents | Un usuario bifurca un repositorio. Para obtener más información, consulte las "bifurcaciones" de la API de REST. |
gollum | contents | Se crea o actualiza una página de wiki. Para más información, consulte "Acerca de las wikis". |
issues | issues | La actividar relacionada con un informe de problemas. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "incidencias". |
issue_comment | issues | Actividad relacionada con un comentario a una propuesta o solicitud de cambios. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "comentarios de incidencias". |
label | metadata | Actividad relacionada con una etiqueta. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "etiquetas". |
member | members | La actividad relacionada con los colaboradores del repositorio. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, consulta la API REST de "colaboradores". |
membership | members | La actividad relacionada con la membrecía del equipo. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, vea la API REST "miembros del equipo". |
milestone | pull_request | La actividar relacionada con los hitos. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "hitos". |
organization | members | La actividad relacionada con una organización y sus miembros. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "organizaciones". |
page_build | pages | Representa un intento de compilación de un sitio de GitHub Pages, haya sido exitoso o no. Una subida a la rama habilitada de GitHub Pages (gh-pages para las páginas de proyecto, la rama predeterminada para las páginas de usuario y de organización) desencadena este evento. |
project | repository_projects o organization_projects | Actividad relacionada con instancias de project boards. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, vea la API REST de "proyectos". |
project_card | repository_projects o organization_projects | Actividad relacionada con las tarjetas de una instancia de project board. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, vea la API REST de "tarjetas de proyecto". |
project_column | repository_projects o organization_projects | Actividad relacionada con las columnas de una instancia de project board. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "columnas de proyecto". |
public | metadata | Cuando un repositorio privado se hace público. Sin duda alguna: el mejor evento de GitHub Enterprise Server. |
pull_request | pull_requests | La actividad relacionada con las solicitudes de extracción. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "solicitudes de incorporación de cambios". |
pull_request_review | pull_request | La actividad relacionada con las revisiones de la solicitudes de extracción. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, vea la API REST de "revisiones de solicitudes de incorporación de cambios". |
pull_request_review_comment | pull_request | La actividar relacionada con los comentarios de revisión de la solicitud de extracción en el diff unificado de la misma. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para obtener más información, consulte la API de REST de "comentarios de revisiones de solicitudes de incorporación de cambios". |
pull_request_review_thread | pull_request | Actividad relacionada con un hilo de comentarios en una solicitud de incorporación de cambios que se marca como resuelto o sin resolver. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. |
push | contents | Se cargó una o más confirmaciones a la rama o etiqueta de un repositorio. |
release | contents | La actividad relacionada con un lanzamiento. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "versiones". |
repository | metadata | La actividad relacionada con un repositorio. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "repositorios". |
status | statuses | Cuando el estado de una confirmación de Git cambia. Para más información, vea la API REST de "estados". |
team | members | La actividad relacionada con el equipo de una organización. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "equipos". |
team_add | members | Cuando se agrega un repositorio a un equipo. |
watch | metadata | Cuando alguien marca un repositorio con una estrella. El tipo de actividad se especifica en la propiedad action de la acción del objeto de carga. Para más información, vea la API REST de "marcar con estrellas". |