Orbit
Conectar un repositorio de GitLab
GitLab connects to Orbit through OAuth rather than an installed app: you authorise Kapsule once, Orbit lists the projects your GitLab account can reach, and it registers a webhook per repository so…
GitLab se conecta a Orbit a través de OAuth en lugar de una aplicación instalada: autorizas Kapsule una vez, Orbit lista los proyectos que tu cuenta de GitLab puede alcanzar, y registra un webhook por repositorio para que cada push dispare una compilación. Esta guía cubre la conexión, la selección de un repositorio, la restricción de despliegues según tu pipeline de GitLab, y las razones habituales por las que un repositorio no aparece.
Antes de Empezar
Orbit solo puede ver proyectos de GitLab que tu propia cuenta pueda ver. Para un proyecto propiedad de un grupo necesitas al menos acceso Developer, y necesitas permiso suficiente para que se cree un webhook en el repositorio. Si tu instancia de GitLab restringe webhooks salientes, esa restricción se aplica aquí también.
Paso 1: Conectar GitLab
- En KPanel, haz clic en Orbit en la barra lateral izquierda.
- Haz clic en New project.
- Deja el modo configurado en Import Git Repo.
- En el paso 1, haz clic en Connect GitLab.
Se te envía a GitLab para autorizar la aplicación Kapsule Orbit. Aprueba los scopes solicitados y GitLab te devuelve a KPanel con tus repositorios cargados. El paso 1 entonces muestra Just connected.
Si la conexión falla, KPanel muestra el error que GitLab devolvió en lugar de un mensaje genérico. Léelo antes de reintentar: un rechazo de scope y una autorización expirada necesitan correcciones diferentes.
Paso 2: Seleccionar un Repositorio
Tus repositorios accesibles aparecen como una lista. Haz clic en Select junto al que deseas. Los repositorios privados llevan un distintivo Private; Orbit despliega repositorios públicos y privados por igual.
Si Falta un Repositorio
- Comprueba tu rol en el proyecto. El acceso Reporter no es suficiente; necesitas al menos Developer.
- Si el proyecto pertenece a un grupo, confirma que tu pertenencia sea al grupo o al proyecto mismo, no solo a un grupo ancestro con un rol restringido.
- Haz clic en Reconnect GitLab en el paso 1 para volver a ejecutar el flujo OAuth. Esto actualiza el token y vuelve a leer tu lista de proyectos.
Si el panel muestra No repos accessible, la autorización OAuth se realizó pero no devolvió nada. Reconnect y comprueba que aprobaste los scopes del repositorio en lugar de un conjunto reducido.
Paso 3: Configurar tu Proyecto
| Campo | Qué hace |
|---|---|
| Project Name | El nombre de visualización en KPanel, por ejemplo my-app |
| Deploy URL | El subdominio bajo kaps.run, por lo que my-app se convierte en my-app.kaps.run |
Haz clic en Create project. Orbit clona el repositorio, pone la primera compilación en la cola y te lleva a la descripción general del proyecto.
El slug de Deploy URL se fija en la creación y no se puede cambiar posteriormente. Para publicar bajo una dirección diferente, adjunta un dominio personalizado en su lugar. Consulta Adding a Custom Domain to Your Project.
Despliegues Automáticos
Orbit registra un webhook en tu repositorio de GitLab cuando se crea el proyecto. Después de eso:
- Un push a tu rama de producción pone en cola un despliegue de producción.
- Un push a cualquier otra rama construye una vista previa aislada en
branch-<branch-name>.kaps.run, si Branch previews está habilitado en Settings bajo Runtime. Consulta Branch Preview Deployments in Orbit. - Eliminar una rama pausa su entorno de vista previa, y el almacenamiento se recupera en aproximadamente un día.
No creas ni mantengas el webhook manualmente.
Esperar Tu Pipeline de GitLab CI
Si ejecutas pruebas en GitLab CI, Orbit puede mantener el despliegue hasta que el pipeline pase.
- Abre el proyecto, luego Settings.
- Encuentra CI required checks.
- Introduce cualquier valor no vacío y guarda.
En GitLab, el valor en sí no se compara contra nombres de trabajos: cualquier valor no vacío le dice a Orbit que espere a que el pipeline completo tenga éxito. Un fallo del pipeline cancela el despliegue de Orbit automáticamente. Esto se aplica solo a despliegues desencadenados por push en la rama de producción.
Aquí es donde los dos proveedores difieren. GitHub compara el valor contra trabajos de Actions nombrados; GitLab trata cualquier valor como "espera todo el pipeline". Si estás copiando configuración entre un proyecto de GitHub y uno de GitLab, no esperes que el mismo campo se comporte de forma idéntica.
Reconectar o Desconectar GitLab
- Haz clic en Orbit, luego New project.
- En el paso 1, haz clic en Reconnect para volver a ejecutar el flujo OAuth, o Disconnect para eliminar el vínculo.
Reconnect es el primer movimiento correcto cuando el listado de repositorios deja de funcionar: los tokens OAuth caducan, y reconectar acuña uno nuevo.
Desconectar mantiene tus proyectos y su historial de despliegue, y el despliegue activo continúa sirviendo tráfico. Lo que se detiene es el despliegue desencadenado por push. Los hooks de despliegue también dejan de funcionar, porque un hook tiene que leer la cabeza de rama a través de la conexión del proveedor para saber qué compilar.
Lecturas Relacionadas
- Deploying Your Project para el ciclo de despliegue completo, bloqueos de despliegue y aprobaciones
- Troubleshooting Failed Builds si la primera compilación no tiene éxito
- Connecting a GitHub Repo y Connecting a Bitbucket Repo para los otros proveedores