Integración con GitHub

Conectar un proyecto con su repositorio GitHub permite a Quiet Guard seguir el trabajo que despliega su aplicación y correlacionar los errores de producción con el commit que los introdujo.

En los planes de pago. La integración con GitHub forma parte de Indie y Studio. En Free, los ajustes del proyecto muestran lo que hace la integración en lugar de los campos del repositorio. Todo lo ya sincronizado sigue visible en la pestaña GitHub del proyecto; no se recupera nada nuevo mientras el plan no la incluya.

Conectar un repositorio

En la página Ajustes del proyecto, sección Integración con GitHub, indique:

• Repositorio: el repositorio en la forma propietario/nombre (por ejemplo acme/store), tal como aparece en la dirección de GitHub.
• Token de acceso: un token de acceso personal de GitHub capaz de leer ese repositorio. Quiet Guard solo lee tres cosas: los metadatos del repositorio, sus commits y ramas, y sus pull requests. Nunca escribe, salvo para abrir una issue desde una incidencia si usted lo autoriza (véase más abajo).

Crear el token en GitHub

1. Con una sesión de GitHub que vea el repositorio, abra Settings > Developer settings > Personal access tokens > Fine-grained tokens y después Generate new token. Dirección directa: https://github.com/settings/personal-access-tokens/new.
2. Resource owner: el usuario o la organización propietaria del repositorio. Para el repositorio de una organización, elija la organización, no su propia cuenta; algunas organizaciones exigen que un administrador apruebe el token antes de que funcione.
3. Repository access: Only select repositories, y a continuación el único repositorio en cuestión.
4. Repository permissions: Contents en Read-only (commits y ramas) y Pull requests en Read-only. GitHub añade Metadata en Read-only por sí mismo. Para seguir las issues del repositorio, añada Issues en Read-only; para abrir una desde una incidencia, Issues en Read and write. Nada más.
5. Expiration: lo que permita su política. Al caducar, la sincronización se detiene y no aparece nada nuevo en la pestaña GitHub hasta que pegue un token nuevo.
6. Genere el token y cópielo (empieza por github_pat_): GitHub lo muestra una sola vez.

Péguelo en el campo Token de acceso y guarde. El campo nunca vuelve a mostrar el token almacenado: déjelo vacío en los guardados posteriores para conservar el actual, escriba uno nuevo para sustituirlo.

Un token personal classic también funciona, con el alcance repo para un repositorio privado o public_repo para uno público. Es preferible el de alcance restringido: se limita a un solo repositorio y a permisos de solo lectura, que es todo lo que usa esta integración.

El token se cifra en reposo. La columna github_token se almacena mediante el cast cifrado de Laravel; el token, por tanto, nunca se persiste en claro en la base de datos.

Un proyecto se considera conectado a GitHub en cuanto hay presentes un repositorio y un token. Ejecute Sincronizar GitHub una vez justo después de guardar: es la forma más rápida de descubrir que un token no abre el repositorio.

Qué se sincroniza

La sincronización recupera y almacena tres tipos de actividad del repositorio, y un cuarto a petición:

• Commits: los commits recientes, con SHA, mensaje, autor y marca de tiempo.
• Pull requests: las PR abiertas y recientes.
• Ramas: las ramas del repositorio, reconciliadas en cada sincronización (las ramas desaparecidas en el origen se eliminan localmente).
• Issues, si el proyecto lo ha pedido: las issues del repositorio, sus etiquetas y, opcionalmente, sus comentarios (véase Las issues del repositorio).

La sincronización sigue un enfoque de recuperar todo y luego escribir todo en una transacción: los datos se extraen primero de la API REST de GitHub y después se escriben en una sola transacción, para que un fallo de red parcial nunca deje el proyecto actualizado a medias.

Lanzar una sincronización

Use la acción Sincronizar GitHub de la pestaña GitHub (menú Ajustes del proyecto) para recuperar la última actividad bajo demanda. Los commits, PR y ramas sincronizados se muestran en la pestaña GitHub del proyecto.

En los planes que incluyen la integración, un proyecto conectado también se sincroniza por su cuenta, unas cuantas veces al día, para que la imagen siga al día entre dos despliegues sin que nadie haga clic.

Las issues del repositorio

Las issues de GitHub son la conversación del equipo: traerlas al panel es una elección, no un efecto secundario del token pegado para los commits. En la página Ajustes del proyecto, sección Integración GitHub, cuatro interruptores, todos apagados por defecto:

• Seguir las issues del repositorio: en cada sincronización, las issues abiertas del repositorio llegan a la pestaña GitHub del proyecto, bajo Issues, con su título, su autor, sus etiquetas y el número de comentarios. Las pull requests que GitHub lista entre las issues se descartan, tienen su propia pestaña.
• Recuperar también los comentarios: una petición a GitHub por issue comentada, limitada a las treinta issues más recientes en cada sincronización. Un comentario eliminado en GitHub desaparece en la siguiente sincronización.
• Incluir las issues cerradas: sin esta opción, la pestaña solo muestra las issues abiertas. Las cerradas siguen sincronizadas, para que una issue vinculada a una incidencia diga cuándo se cierra. Una sincronización lee las 100 issues más recientes del repositorio.
• Abrir una issue de GitHub por cada incidencia nueva: véase más abajo.

Desde la pestaña, Leer abre una issue y sus comentarios sin salir del panel; el Markdown se renderiza con el mismo motor que esta documentación, que escapa todo antes de mostrarlo. Abrir en GitHub lleva a la issue misma. El token necesita el permiso Issues en lectura.

Desde una incidencia

En la página de una incidencia, dos acciones aparecen en cuanto el proyecto sigue sus issues:

• Abrir una issue de GitHub propone un título y una descripción compuestos a partir de los metadatos de la incidencia: la clase de la excepción, la ubicación, el primer marco en su código, el número de ocurrencias, los entornos y versiones afectados, y el enlace a la incidencia. El mensaje de la excepción solo figura si no está cifrado: un equipo que sella su contenido nunca lo ve copiado a GitHub por esta acción. Revise y modifique antes de enviar, el texto es público si el repositorio lo es. La issue se crea con la etiqueta quiet-guard y se vincula a la incidencia, que la muestra después en su vista general.
• Vincular una issue de GitHub asocia la incidencia a una issue abierta ya sincronizada, para un informe que alguien escribió antes que usted.

La pestaña Issues del proyecto muestra, para cada issue, la incidencia que sigue.

Con Abrir una issue de GitHub por cada incidencia nueva, la primera ocurrencia de una excepción nunca vista abre la issue por sí misma, con el mismo cuerpo, sin que nadie haga clic. Una regresión (una incidencia resuelta que se reproduce) no abre una nueva: la issue que tenía sigue ahí. Un rechazo de GitHub (un token sin permiso de escritura, un repositorio archivado) se registra y nunca detiene la ingestión; la issue puede abrirse entonces a mano. Como máximo se abren así diez issues por hora y por proyecto: una clave de proyecto filtrada puede fabricar incidencias a voluntad, y no debe llenar su repositorio en su nombre.

Abrir una issue exige al token el permiso Issues en Read and write; es la única escritura que la integración hace en su repositorio.

Correlación release → commit

Aquí es donde los datos de GitHub dan sus frutos. Cuando una ocurrencia de excepción lleva un valor release que es un SHA de commit, Quiet Guard lo resuelve hacia el commit sincronizado correspondiente. Desde la issue puede abrir el commit exacto que estaba desplegado en el momento del error.

El mismo commit sirve para la traza de llamadas: en la página de una incidencia, cada marco de su aplicación ofrece Abrir este archivo en GitHub, en la línea exacta, en el commit desplegado cuando se produjo la ocurrencia (en su defecto, en la rama por defecto del repositorio).

Para que esto se resuelva, deben cumplirse dos condiciones:

1. Su aplicación envía el SHA del commit desplegado en context.release del payload de excepción.
2. Ese commit ha sido sincronizado desde GitHub.

Consejo: el SDK de Laravel detecta el SHA por sí mismo desde el checkout o un archivo REVISION, y la página de configuración ofrece una receta por cada forma de despliegue (Forge, Envoyer, GitHub Actions, Docker). Después, lance una sincronización GitHub tras cada despliegue, para que el vínculo error → commit esté siempre disponible.