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 de usuario:
http(s)://[hostname]/settings/apps/new - Cuenta organizacional:
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 incluyes los parámetros requeridos en la secuencia de consulta de la URL, como el name, el creador de la app necesitará ingresar un valor antes de emitirla.
La siguiente URL crea una app pública nueva que se llama octocat-github-app con una descripción preconfigurada y una URL de rellamado. Esta URL también selecciona los permisos de lectura y escritura para las checks, se suscribe a los eventos de webhook de 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_url=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 (nombre) | secuencia | El nombre de la GitHub App. Pónle un nombre claro y breve a tu app. Tu app no puede tener el mismo nombre que un usuario de 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. |
descripción | secuencia | Una descripción de la GitHub App. |
url | secuencia | La URL completa de tu página principal del sitio web de la GitHub App. |
callback_url | secuencia | La URL completa a la cual se redirigirá después de que alguien autorice la instalación. Esta URL se utiliza si tu app necesita identificar y autorizar solicitudes de usuario a servidor. |
request_oauth_on_install | boolean | Si tu app autoriza a los usuarios mediante el flujo de OAuth, puedes configurar esta opción como true para permitir que las personas autoricen la app cuando la instalen, lo cual te ahorra un paso. Si seleccionas esta opción, la setup_url deja de estar disponible y se redirigirá a los usuarios a tu callback_url después de que instalen la app. |
setup_url | secuencia | 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 | Configúralo como true para redireccionar a las personas a la URL de ajustes cuando las instalaciones se actualicen, por ejemplo, después de que se agreguen o eliminen repositorios. |
public | boolean | Configúralo como true cuando tu GitHub App se encuentre disponible al público, o como false cuando solo el propietario de la misma tenga acceso a ella. |
webhook_active | boolean | Configurar como false para inhabilitar el webhook. El webhook se encuentra habilitado predeterminadamente. |
webhook_url | secuencia | La URL completa a la cual quisieras enviar cargas útiles de eventos de webhook. |
webhook_secret | secuencia | Puedes especificar un secreto para asegurar tus webhooks. Consulta la sección "Asegurar tus webhooks" para obtener más detalles. |
events | conjunto de secuencias | Eventos de webhook. Algunos eventos de webhook requieren asignar permisos de read o de write a un recurso antes de que puedas seleccionar el evento cuando registras una GitHub App nueva. Consulta la sección "Eventos de webhook de las GitHub App" para encontrar los eventos disponibles y sus permisos requeridos. Puedes seleccionar eventos múltiples en una secuencia de consulta. Por ejemplo, events[]=public&events[]=label. |
dominio | secuencia | La URL de una referencia de contenido. |
single_file_name | secuencia | Este es un permiso con alcance corto que permite a la app acceder a un solo archivo en cualquier repositorio. Cuando configuras el permiso de single_file en read o write, este campo proporciona la ruta al archivo único que administrará tu GitHub App. Si necesitas administrar varios archivos, consulta la opción single_file_paths a continuación. |
single_file_paths | conjunto de secuencias | Esto permite a la app acceder hasta a 10 archivos especificos en un repositorio. Cuando configuras el permiso single_file en read o write, este arreglo puede almacenar las rutas de hasta diez archivos que administrará tu GitHub App. Estos archivos reciben el mismo permiso que se configuró para single_file, y no tienen permisos individuales por separado. Cuando dos o mas archivos se configuran, la API devuelve multiple_single_files=true, de lo contrario, devuelve 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 los permisos de Read & write en la interface de usuario para contents, tu secuencia de consulta incluiría &contents=write. Para seleccionar los permisos de Read-only en la interface de usuario para blocking, tu secuencia de consulta incluiría &blocking=read. Para seleccionar no-access en la interface de usuario para las checks, tu secuencia de consulta no incluiría el permiso checks.
| Permiso | Descripción |
|---|---|
administration | Otorga acceso a diversas terminales para la administración de organizaciones y repositorios. Puede ser uno de entre none, read, o write. |
verificaciones | Otorga acceso a la API de verificaciones. Puede ser uno de entre none, read, o write. |
content_references | Otorga acceso a la terminal "Crear un adjunto de contenido". Puede ser uno de entre none, read, o write. |
contenidos | Otorga acceso a diversas terminales que te permiten modificar el contenido de los repositorios. Puede ser uno de entre none, read, o write. |
implementaciones | Otorga acceso a la API de despliegues. Puede ser uno de entre none, read, o write. |
emails | Otorga acceso a la API de Correos electrónicos. Puede ser uno de entre none, read, o write. |
followers | Otorga acceso a la API de Seguidores. Puede ser uno de entre none, read, o write. |
gpg_keys | Otorga acceso a la API de Llaves GPG. Puede ser uno de entre none, read, o write. |
propuestas | Otorga acceso a la API de Informe de problemas. Puede ser uno de entre none, read, o write. |
keys | Otorga acceso a la API de Llaves Públicas. Puede ser uno de entre none, read, o write. |
members | Otorga acceso para administrar los miembros de una organización. Puede ser uno de entre none, read, o write. |
organization_hooks | Otorga acceso a la API de Webhooks de la Organización. Puede ser uno de entre none, read, o write. |
organization_plan | Otorga acceso para obtener información acerca del plan de una organización que utilice la terminal "Obtener una organización". Puede ser uno de entre none o read. |
organization_projects | Otorga acceso a la API de Proyectos. Puede ser uno de entre: none, read, write, o admin. |
páginas | Otorga acceso a la API de páginas. Puede ser uno de entre none, read, o write. |
plan | Otorga acceso para obtener información acerca del plan de GitHub de un usuario que utilice la terminal "Obtener un usuario". Puede ser uno de entre none o read. |
pull_requests | Otorga acceso a varias terminales de solicitud de extracción. Puede ser uno de entre none, read, o write. |
repository_hooks | Otorga acceso a la API de Webhooks del Repositorio. Puede ser uno de entre none, read, o write. |
repository_projects | Otorga acceso a la API de Proyectos. Puede ser uno de entre: none, read, write, o admin. |
security_events | Otorga acceso a la API de escaneo de código. Puede ser uno de entre none, read, o write. |
single_file | Otorga acceso a la API de Contenidos. Puede ser uno de entre none, read, o write. |
starring | Otorga acceso a la API de marcar con estrella. Puede ser uno de entre none, read, o write. |
estados | Otorga acceso a la API de Estados. Puede ser uno de entre none, read, o write. |
team_discussions | Otorga acceso a la API de debates de equipo y a la API de comentarios en debates de equipo. Puede ser uno de entre none, read, o write. |
vulnerability_alerts | Otorga acceso para recibir alertas de seguridad para las dependencias vulnerables en un repositorio. Consulta la sección "Acerca de las alertas para las dependencias vulnerables" para aprender más. Puede ser uno de entre: none o read. |
observando | Otorga acceso a la lista y cambia los repositorios a los que un usuario está suscrito. Puede ser uno de entre none, read, o write. |
Eventos de webhook de GitHub App
| Nombre del evento de webhook | Permiso requerido | Descripción |
|---|---|---|
check_run | verificaciones | Ha ocurrido una actividad de ejecución de verificación. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "ejecuciones de verificación". |
check_suite | verificaciones | Ha ocurrido una actividad de suite de verificaciones. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "suites de verificaciones". |
comentario_confirmación de cambios | contenidos | Se creó un comentario de una confirmación. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "comentario de confirmación". |
content_reference | content_references | Una referencia de contenido nueva se muestra como 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 obtener más información, consulta la sección "Utilizar adjuntos de contenido" para aprender más sobre las referencias de contenido y sus adjuntos. |
create (crear) | contenidos | Se crea una rama o etiqueta de Git. Para obtener más información, consulta la API de REST de "Git database". |
delete | contenidos | Se borra una rama o etiqueta de Git. Para obtener más información, consulta la API de REST de "Base de datos de Git". |
deployment | implementaciones | Se crea un despliegue. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "despliegue". |
deployment_status | implementaciones | Se crea un despliegue. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "deployments". |
bifurcación | contenidos | Un usuario bifurca un repositorio. Para obtener más información, consulta la API de REST de "bifurcaciones". |
gollum | contenidos | Se crea o actualiza una página de wiki. Para obtener más información, consulta la sección "Acerca de los wikis". |
propuestas | propuestas | La actividar relacionada con un informe de problemas. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "informe de problemas". |
comentario_propuesta | propuestas | Actividad relacionada con un comentario a una propuesta o solicitud de cambios. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "comentrios del informe de problemas". |
etiqueta | metadatos | Actividad relacionada con una etiqueta. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "etiquetas". |
miembro | members | La actividad relacionada con los colaboradores del repositorio. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "colaboradores". |
membership | members | La actividad relacionada con la membrecía del equipo. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "miembros del equipo". |
hito | solicitud_extracción | La actividar relacionada con los hitos. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de 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 del objeto de la carga útil. Para obtener más información, consulta la API de REST de "organizaciones". |
page_build | páginas | Representa un intento de compilación de un sitio de Páginas de GitHub, haya sido exitoso o no. Una subida a la rama habilitada de Páginas de GitHub (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 u organization_projects | La actividad relacionada con los tableros de proyecto. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "proyectos". |
project_card | repository_projects u organization_projects | La actividad relacionada con las tarjetas de proyecto. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "tarjetas de proyecto". |
project_column | repository_projects u organization_projects | La actividad relacionada con las columnas en un tablero de proyecto. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "columnas de proyecto". |
public | metadatos | Cuando un repositorio privado se hace público. Sin duda alguna: el mejor evento de GitHub Enterprise Server. |
solicitud_extracción | pull_requests | La actividad relacionada con las solicitudes de extracción. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "solicitudes de extracción". |
revisión_solicitud de extracción | solicitud_extracción | La actividad relacionada con las revisiones de la solicitudes de extracción. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "revisiones de la solicitud de extracción". |
comentarios _revisiones_solicitudes de extracción | solicitud_extracción | 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 del objeto de la carga útil. Para obtener más información, consulta la API de REST de "comentrios de revisión de la solicitud de extracción". |
subir | contenidos | Se cargó una o más confirmaciones a la rama o etiqueta de un repositorio. |
lanzamiento | contenidos | La actividad relacionada con un lanzamiento. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "lanzamientos". |
repositorio | metadatos | La actividad relacionada con un repositorio. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "repositorios". |
estado | estados | Cuando el estado de una confirmación de Git cambia. Para obtener más información, consulta la API de REST de "statuses". |
equipo | members | La actividad relacionada con el equipo de una organización. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "equipos". |
team_add | members | Cuando se agrega un repositorio a un equipo. |
observar | metadatos | Cuando alguien marca un repositorio con una estrella. El tipo de actividad se especifica en la propiedad action del objeto de la carga útil. Para obtener más información, consulta la API de REST de "marcar con una estrella". |