Integración con GitHub

Los repositorios Git son el eje central de la gran mayoría de los proyectos de software. Nos integramos con GitHub para ofrecerte información de Tuist directamente en tus pull requests y ahorrarte configuración, como la sincronización de tu rama predeterminada.

Configuración#

Deberás instalar la aplicación de GitHub de Tuist en la pestaña Integrations de tu organización:

También puedes instalar la aplicación directamente desde GitHub. Inicia sesión en Tuist si es necesario, autoriza la aplicación de GitHub para que Tuist pueda verificar tu acceso a la instalación y elige la organización de Tuist que deseas conectar. Debes ser propietario de la organización de GitHub (o de la cuenta personal de GitHub) donde se instala la aplicación. Solo están disponibles las organizaciones de Tuist que administras y tu cuenta personal de Tuist. Si solo hay una cuenta disponible, Tuist la conecta automáticamente sin mostrar el selector. Cuando inicias desde Tuist, la organización ya está seleccionada y este paso se omite.

Después, puedes añadir una conexión de proyecto entre tu repositorio de GitHub y tu proyecto de Tuist:

Una vez instalada la aplicación, también puedes vincular un proyecto sin usar el panel:

• CLI:tuist project repository connect owner/name, y tuist project repository disconnect para eliminar el vínculo.
• API REST:PUT y DELETE en /api/projects/{account_handle}/{project_handle}/vcs-connection.
• Model Context Protocol: las herramientas connect_project_repository y disconnect_project_repository.

El repositorio debe ser accesible para la instalación de la aplicación de GitHub y el proyecto adopta la rama predeterminada del repositorio. Los tokens de cuenta necesitan el ámbito project:admin:write.

GitHub Enterprise Server#

Tuist también se integra con instancias autoalojadas de GitHub Enterprise Server (GHES). En la tarjeta de integración de GitHub, cambia a la pestaña Servidor empresarial, introduce la URL base de tu GHES (por ejemplo, https://github.example.com) y haz clic en instalar.

Dado que las aplicaciones de GitHub están limitadas a una única instancia de GitHub, Tuist no puede reutilizar su aplicación de github.com en tu GHES; en su lugar, el botón de instalación te guía a través del flujo de manifiesto de la aplicación de GitHub: GHES acompaña a tu administrador en el registro de una nueva aplicación de Tuist en la instancia y luego devuelve las credenciales de la nueva aplicación a Tuist. Tuist almacena esas credenciales cifradas por instalación y las utiliza para cada llamada a la API, firma de webhook y enlace a tus repositorios a partir de entonces.

No se necesita configuración adicional del servidor de Tuist; el flujo de manifiesto genera y aprovisiona todo automáticamente.

Permisos de la aplicación y eventos de webhook#

Tuist requiere los siguientes permisos de repositorio para comentarios en PR y comprobaciones del tamaño del bundle:

Tuist utiliza el evento de webhook check_run para gestionar las acciones de comprobación del tamaño del bundle. El flujo de manifiesto configura esta suscripción automáticamente.

Para la configuración manual de la aplicación en github.com con un servidor de Tuist autoalojado, consulta la guía de autoalojamiento.

URLs separadas para el navegador y la API#

Si los ingenieros acceden a GitHub Enterprise a través de un nombre de host interno mientras los servicios de terceros utilizan un proxy externo, configura ambas direcciones antes de hacer clic en instalar:

La URL de la API es la URL base completa de la API REST, incluido /api/v3 o la ruta equivalente expuesta por tu proxy. Tuist no añade /api/v3 a una URL de API explícita. Déjala vacía si un único nombre de host funciona tanto para tu navegador como para Tuist; las conexiones existentes seguirán usando <Server URL>/api/v3.

Ambas direcciones deben enrutar hacia la misma instancia de GitHub Enterprise. Tu navegador solo necesita alcanzar la URL del servidor, no el proxy de la API. Los servidores de Tuist solo necesitan alcanzar la URL de la API, no el nombre de host interno del navegador.

Para el proxy externo:

• Utiliza HTTPS con un certificado de confianza para los servidores de Tuist y DNS público que resuelva a direcciones IP públicas. Las anulaciones de la URL de la API no omiten las protecciones de IP privada/SSRF de Tuist. La anulación debe dirigirse a tu instancia Enterprise, no a github.com ni a un extremo *.github.com.
• Añade a la lista blanca cada dirección IP saliente de Tuist.
• Reenvía los extremos de la API REST que utiliza Tuist, incluidos POST /api/v3/app-manifests/{code}/conversions, POST /api/v3/app/installations/{installation_id}/access_tokens y los extremos de la API del repositorio para comentarios y checks. Estas son las rutas upstream de GitHub; tradúcelas si tu proxy expone un prefijo diferente.
• Reenvía las solicitudes a GitHub sin redirecciones HTTP ni una página de inicio de sesión interactiva. Tuist no sigue automáticamente las redirecciones de la API Enterprise, por lo que no pueden omitir las comprobaciones de IP pública. El extremo de conversión del manifiesto debe ser accesible durante la configuración, antes de que Tuist tenga las credenciales de la aplicación. Las descargas de registros de GitHub Actions son una excepción: Tuist sigue las redirecciones de archivos firmados solo a través de HTTPS, verifica y fija cada destino a una IP pública y no reenvía el token de instalación.

GitHub puede devolver enlaces de paginación utilizando su nombre de host interno. Tuist reajusta los enlaces desde la instancia de GitHub configurada a la URL de la API, conservando el prefijo de ruta de tu proxy; los enlaces a orígenes no relacionados se rechazan.

Por separado, GitHub debe poder entregar webhooks a https://tuist.dev/webhooks/github (o /webhooks/github en tu servidor de Tuist autoalojado). Los ingenieros deben poder volver a Tuist para completar las devoluciones de llamada del navegador. La URL de la API no cambia ninguno de estos destinos.

Los administradores de la organización también pueden cambiar o borrar la URL de la API en una integración Enterprise existente usando Guardar URL de la API en la tarjeta de integración. No es necesario reinstalar la aplicación ni reconectar el proyecto. Borrarla restaura <Server URL>/api/v3. Al guardar se valida el formato de la URL, no la conectividad del proxy. El procesamiento de webhooks puede tardar hasta un minuto en utilizar una dirección cambiada porque las búsquedas de instalaciones están almacenadas en caché; las solicitudes ya en curso pueden seguir utilizando la dirección anterior.

Comentarios en pull/merge requests#

La aplicación de GitHub publica un informe de ejecución de Tuist, que incluye un resumen del PR, con enlaces a las últimas previsualizaciones o tests:

Tuist actualiza un único comentario a medida que llegan los resultados. Las compilaciones de Gradle aparecen por separado para cada proyecto raíz y conjunto de tareas solicitadas; volver a ejecutar las mismas tareas sustituye el resultado anterior de esa invocación. El historial completo de compilaciones sigue estando disponible en Tuist.

Los comentarios están habilitados de forma predeterminada, conservando los informes para las integraciones existentes. Para desactivarlos o volver a activarlos para un proyecto, abre Configuración del proyecto → Integraciones y alterna GitHub → Comentarios del informe de ejecución. Cada proyecto tiene su propia configuración; las conexiones de repositorio siguen gestionándose en la configuración de la organización.

Desactivar los comentarios no desactiva las subidas de compilaciones o tests, los resúmenes de trabajos de GitHub Actions, las conexiones de repositorio ni otras funcionalidades de integración de GitHub. Los comentarios existentes no se eliminan.

Resumen del trabajo de GitHub Actions#

La CLI de Tuist y el plugin de Gradle escriben los resultados de tests y compilaciones en el resumen del trabajo en GitHub Actions. El resumen enlaza al informe completo en Tuist, donde hay disponibles análisis más detallados, como tests inestables y deltas del tamaño del bundle.

Para Gradle, cada informe de compilación o test subido correctamente añade su propio resumen, conservando otro contenido escrito por herramientas como gradle/actions/setup-gradle. Esto requiere una versión del plugin que incluya compatibilidad con resúmenes de trabajos; las versiones anteriores del plugin de Gradle solo informan a través del comentario de PR de la aplicación de GitHub. La aplicación de GitHub no necesita estar conectada para los resúmenes de trabajos, y desactivar Comentarios del informe de ejecución no les afecta.

Cuando hay disponible un destino de resumen de GitHub Actions, Gradle espera a que finalicen las subidas y los resúmenes antes de salir, incluso si uploadInBackground está habilitado. GitHub captura el resumen cuando finaliza el paso del flujo de trabajo.

Esto es especialmente útil con colas de merge. Una ejecución de cola de merge no está asociada a un pull request, por lo que no se publica ningún comentario, pero el resumen del trabajo sigue mostrando los resultados.