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.

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. 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:

• 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).

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 Sync GitHub en el 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.

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.

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: configure su pipeline de despliegue para fijar la release al SHA de Git desplegado, y lance una sincronización GitHub tras cada despliegue, para que el vínculo error → commit esté siempre disponible.