Hosting de Git

Las integraciones de Git deciden desde qué repositorios puede construir Opfield. Un commit concreto se puede rastrear a través de su build hasta un artefacto inmutable y la versión que lo ejecuta.

Configura las integraciones de código en Settings > Integrations. Los proveedores compatibles son GitLab, GitHub y Git genérico. Los conectores de GitHub y de Git genérico están disponibles en todos los planes; la integración con GitLab, incluido el descubrimiento de registros de GitLab, requiere Personal o superior. Los conectores de GitLab creados en Community antes de la 2.11 se conservan, pero no se pueden abrir hasta que haya activa una clave Personal o superior. Los builds desde orígenes Git requieren Business o Enterprise. Para acceder a un sistema operativo remoto, usa la guía aparte de Conexiones SSH.

Usa una identidad de máquina o de aplicación dedicada con acceso de solo lectura a los repositorios salvo que un flujo de trabajo requiera explícitamente más. Restringe los repositorios y los hosts permitidos. Verifica la autenticidad de los webhooks, la selección de ramas, la resolución de commits y la rotación de credenciales.

Las URL de los repositorios no deben contener credenciales incrustadas. Las claves de host SSH y la validación de certificados HTTPS deben fallar de forma segura. Elimina una integración solo después de identificar y migrar los orígenes de Docker, Compose y Pages que dependen de ella.

Tipos de integración

GitLab: descubrimiento de proyectos y grupos, operaciones con repositorios, webhooks, variables, flujos de trabajo relacionados con CI y descubrimiento opcional de registros según los derechos del plan.
GitHub: descubrimiento de repositorios y operaciones compatibles con repositorios y Actions a través de la aplicación o el token configurados.
Git genérico: acceso autenticado y acotado a repositorios cuando no se necesita un proveedor de primer nivel.

GitLab

Usa un usuario de GitLab dedicado que solo sea miembro de los grupos y proyectos necesarios. En GitLab, abre el menú del avatar, Edit profile > Access > Personal access tokens. Crea un token (la interfaz puede llamarlo legacy personal access token).
Fija su nombre y su caducidad y elige los permisos de la tabla. Copia el secreto de inmediato.
En la integración de GitLab de Opfield, introduce el origen de la instancia, como https://gitlab.example.com, sin /api/v4, y el token. Selecciona los proyectos y grupos permitidos en lugar de conceder todos los proyectos descubiertos.
Prueba el token, descubre un proyecto permitido y verifica el acceso al repositorio y a la rama. Un deploy token de GitLab no sustituye a esta identidad de API.

Flujo de trabajo	Ámbitos del token de GitLab
Descubrir proyectos y leer metadatos de la API	`read_api`
Leer o clonar el código del repositorio para los builds	`read_repository` junto con `read_api` para el conector de primer nivel
Descubrir o descargar imágenes del registro privado	Añade `read_registry` y la pertenencia necesaria al proyecto
Escribir archivos a través de la API, gestionar hooks o variables o hacer cambios en CI	`api`; el usuario también debe tener el rol necesario en el proyecto
Hacer push mediante Git sobre HTTPS	`write_repository`; esto no concede acceso general de escritura a la API

Para builds de solo lectura, empieza con read_api + read_repository, no con api. El ámbito amplio api solo es adecuado cuando se activan los flujos de escritura que lo necesitan. Los ámbitos del token no pueden saltarse las reglas de ramas protegidas ni la falta de pertenencia a un proyecto. La autorización de GitLab específica de cada usuario para las herramientas interactivas sigue siendo independiente del token de sistema guardado.

Referencias: Crear un personal access token de GitLab, ámbitos de los access tokens de GitLab.

GitHub

Cuando añades un conector de GitHub, Opfield pregunta cómo autorizarlo. Para GitHub.com, elige OAuth (Recommended): Opfield muestra un código de dispositivo, lo apruebas en GitHub y no se copia ningún token en Opfield. Pide repo, workflow, read:org y read:packages; revisa el acceso a organizaciones y repositorios en la pantalla de consentimiento de GitHub. Para GitHub Enterprise, o para usar un token, elige Personal access token:

Abre en GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic).
Fija un nombre dedicado y una caducidad. Selecciona repo para los repositorios privados, o public_repo si solo se necesitan repositorios públicos. Son permisos amplios sobre los repositorios, no ámbitos de solo lectura: usa una identidad cuyo acceso a los repositorios esté debidamente restringido.
Añade permisos opcionales solo para el flujo de trabajo correspondiente de la tabla siguiente. Genera y copia el token. Autorízalo para el SSO de la organización cuando sea necesario.
Añade el token en la integración de GitHub de Opfield, selecciona los repositorios y las organizaciones permitidos y prueba el descubrimiento de repositorios y la revisión prevista.

Uso adicional	Ámbito del token classic
Leer la pertenencia a organizaciones y equipos	`read:org`
Descargar paquetes de GitHub Packages	`read:packages`
Modificar archivos de workflows	`workflow`, además del acceso al repositorio

Limitación de compatibilidad actual: Opfield detecta las capacidades de los tokens de GitHub a partir de los ámbitos OAuth classic. Un PAT fine-grained puede autenticarse en GitHub y, aun así, este conector puede notificarlo sin capacidades sobre repositorios. No lo uses como sustituto directo de la receta anterior. Si la organización prohíbe los PAT classic, usa la opción OAuth o resuelve la compatibilidad del conector antes de conectar; no debilites la política de la organización. No se necesita ningún ámbito delete_repo ni de administración de la organización solo para construir un repositorio guardado.

Referencias: Gestionar los personal access tokens de GitHub, significado de los ámbitos OAuth classic.

Git genérico

En el servidor Git, crea una credencial dedicada que pueda clonar los repositorios seleccionados. Por ejemplo, un deploy token de GitLab con read_repository se puede usar para el acceso por Git sobre HTTPS; no es un token de la API de GitLab de primer nivel.
En Opfield, elige Git genérico. Introduce Git host URL, como https://git.example.com, y los Repositories explícitos, como https://git.example.com/team/app.git.
Introduce Username y Access token por separado. Para un deploy token, usa el nombre de usuario emitido con ese token. No incluyas ninguno de los dos valores en las URL de los repositorios.
Ejecuta Test Connection y guarda. La prueba de conexión usa el primer repositorio: verifica también el acceso a todos los demás repositorios que permitas antes de depender de ellos para un build.

Este conector usa credenciales HTTPS, no una clave privada importada desde External SSH. No ofrece un vocabulario universal de ámbitos de proveedores Git ni el conjunto completo de funciones de las API de GitLab o GitHub. Un clon correcto no implica permiso para gestionar webhooks, variables ni CI a través de una API.

Configura de forma segura

Crea una identidad de proveedor o de máquina dedicada.
Concede acceso de solo lectura a los repositorios salvo que un flujo de trabajo documentado necesite escrituras.
Restringe las organizaciones, los grupos, los proyectos y los repositorios con el modo de selección compatible del conector.
Añade la integración en Settings → Integrations.
Verifica la identidad TLS o SSH del host antes de guardar las credenciales.
Prueba el descubrimiento de repositorios y el acceso a una revisión permitida.
Prueba que se deniega un repositorio o un host fuera del ámbito.
Configura la autenticidad y la entrega de los webhooks solo cuando funcione el camino de lectura.

Restringe el acceso a los repositorios

La lista de permitidos del conector decide a qué repositorios puede llegar Opfield. Los ámbitos de las integraciones de Git deciden qué usuarios, grupos, tokens de API y concesiones OAuth pueden usarlos. Todos los ámbitos de Git excepto manage se pueden limitar por debajo del conector:

GitLab: un grupo, que también cubre sus subgrupos y todos los proyectos que hay debajo, o un único proyecto. Opfield lee de GitLab los grupos padre de un proyecto, de modo que un proyecto movido a otro grupo sigue a su nuevo grupo.
GitHub: un propietario, que cubre todos los repositorios de esa organización o ese usuario, o un único repositorio.
Git genérico: solo el conector.

La administración del conector (ajustes, tokens, lista de permitidos, sincronización, prueba y eliminación) requiere integrations:<provider>:manage sobre el conector o sin restricción; una concesión sobre un grupo, un propietario, un proyecto o un repositorio nunca la permite.

La forma más rápida de conceder acceso a repositorios es Add Access > Git repositories en el diálogo de grupos, en los permisos adicionales de un usuario o en el diálogo de tokens de API: elige el conector, Every repository o un grupo, un propietario o repositorios concretos, y el nivel de acceso (Use, Read code o Edit code and CI), que fija los ámbitos correspondientes. Para restringir un solo ámbito, abre su restricción en Review N scopes en esos diálogos o en el consentimiento de OAuth y MCP. Marca un conector para cubrir todos sus repositorios, o abre Add groups or projects… o Add owners or repositories… bajo el conector para buscar en el proveedor y seleccionar destinos. Las concesiones guardan los ID numéricos del proveedor, así que los cambios de nombre y los traslados no las rompen; un destino que se ha eliminado desde entonces aparece como Unavailable y se puede seguir quitando.

Con concesiones restringidas:

Las listas de conectores, proyectos y repositorios, incluido el selector de origen de los builds, solo muestran lo que cubren las concesiones. Un proyecto que falta en una lista suele estar fuera de la concesión, no sin sincronizar.
Cada operación con un repositorio comprueba el repositorio (archivos, ramas, commits, pipelines y logs de trabajos, variables, webhooks, deploy tokens, ajustes del registro y clones de sandbox) por igual en la consola, la REST API, AI Workspace y MCP. Un proyecto de GitLab fuera de la concesión responde exactamente igual que un proyecto que no está sincronizado: 404 GITLAB_PROJECT_NOT_FOUND, sin su ruta, de modo que no se pueden sondear los ID de proyecto. Para GitHub y Git genérico, en los que quien llama ya indica el repositorio, una denegación devuelve 403 CONNECTOR_SCOPE_DENIED con el ámbito necesario.
Opfield usa la credencial del conector para un repositorio solo cuando use cubre ese repositorio; en caso contrario, usa la credencial personal del usuario.
Las escrituras, los secretos, los clones de sandbox y la decisión sobre la credencial leen del proveedor en ese momento los grupos de un proyecto de GitLab o el propietario de un repositorio de GitHub, de modo que un repositorio transferido se juzga por dónde está ahora; las lecturas simples pueden usar un valor en caché de hasta cinco minutos. Las sincronizaciones del conector y las entregas de webhooks de los orígenes vacían la caché.
El selector de búsqueda solo ofrece destinos dentro de la lista de permitidos del conector y está limitado a 60 peticiones por minuto por cuenta; por encima de eso devuelve 429 SCOPE_TARGET_RATE_LIMITED con Retry-After.
Los tokens de API y las concesiones OAuth conservan sus propias restricciones y además se comprueban en cada petición contra las concesiones actuales de su propietario. Un token restringido a un proyecto funciona mientras su propietario tenga el grupo que contiene el proyecto y deja de funcionar cuando el propietario pierde ese acceso.

Consulta Restricciones de las integraciones de Git para ver el formato exacto de los calificadores y los endpoints del selector.

Ciclo de vida de las vinculaciones de origen

¿Quién puede hacer builds y ver los resultados?

El descubrimiento de repositorios y las operaciones directas con el código usan los ámbitos de las integraciones de los proveedores. GitLab, GitHub y Git genérico comparten los mismos verbos: integrations:<provider>:view enumera los conectores, :manage los configura, los prueba y los sincroniza, :use usa la propia credencial del conector, y :repo:read y :repo:write leen o cambian el contenido de los repositorios. Enumerar y leer los proyectos sincronizados de GitLab requiere integrations:gitlab:view. repo:read de GitLab cubre los archivos del repositorio, los pipelines de CI y los logs de los trabajos, y las claves de las variables de CI/CD, nunca sus valores; cambiar variables requiere repo:write, y leer los valores de las variables de GitHub Actions requiere integrations:github:repo:write. Los grupos integrados viewer y operator solo reciben integrations:gitlab:view. Consulta la referencia de ámbitos. Cada uno de estos ámbitos se puede limitar a un conector, a un grupo o proyecto de GitLab, o a un propietario o repositorio de GitHub; consulta Restringe el acceso a los repositorios.

Asociar o cambiar una vinculación de origen requiere integrations:<provider>:use sobre el repositorio, junto a los permisos propios de la carga de trabajo. Basta con use limitado a ese proyecto o repositorio; no se necesitan repo:read ni una credencial personal del proveedor, porque los builds usan la credencial del conector. Por eso, el grupo integrado operator puede ver los proyectos de GitLab en el selector de origen, pero no puede guardar un origen hasta que se le concede integrations:gitlab:use, preferiblemente limitado a los proyectos que construye. Las herramientas interactivas de GitLab en AI Workspace piden la autorización de GitLab propia del usuario cuando use no cubre el proyecto.

Iniciar un build desde un origen ya guardado es una acción sobre el recurso (docker:containers:manage para los contenedores y los Deployments, docker:compose:manage para Compose y pages:deploy para Pages) y además vuelve a comprobar el integrations:<provider>:use de quien llama sobre el repositorio guardado, de modo que revocar use detiene las reconstrucciones manuales. Sigue sin necesitarse repo:read. Opfield también comprueba el conector guardado, el repositorio permitido y las credenciales del origen.

Los builds automáticos por sondeo y por webhooks dependen de cuándo se guardó el origen por última vez:

Los orígenes guardados antes de la 2.11 siguen construyéndose automáticamente exactamente como antes.
Los orígenes creados o guardados de nuevo desde entonces solo se construyen automáticamente mientras la cuenta que los guardó por última vez sigue teniendo integrations:<provider>:use sobre el repositorio y está activa. En caso contrario, no se ejecuta ningún build: el historial de builds muestra un build cancelado con SOURCE_OWNER_ACCESS_REVOKED y el mensaje Build paused: <user> no longer has use on <repo>, registrado una vez por commit, y el origen muestra el mismo mensaje como su error de sondeo o de webhook. Las entregas de webhooks se siguen aceptando. Los builds automáticos se reanudan cuando la cuenta recupera use, o cuando alguien que lo tiene vuelve a guardar el origen.

Concede use a los equipos que guardan orígenes, limitado a sus proyectos, antes de depender de los builds automáticos.

El historial y los logs de los builds requieren acceso de visualización al destino: docker:containers:view, docker:compose:view o pages:view. Se aplican las restricciones de recurso y de carpeta heredadas. Desde la 2.11, cualquier ámbito de acción sobre el mismo destino, como docker:containers:manage, también concede su visualización. No concedas acceso a repositorios o a nodos de toda la cuenta para sortear la falta de una concesión sobre el destino. Consulta Permisos.

Vinculaciones de origen guardadas

Las cargas de trabajo Docker, los Compose Projects y los Pages Projects crean sus propias vinculaciones de origen. Una vinculación de origen registra la integración, el repositorio, la selección de la revisión, la configuración del build, la política de automatización y los Build Secrets limitados al origen.

Eliminar una integración no hace que sea seguro reconstruir los recursos dependientes. Inventaría primero las dependencias, desactiva las acciones automáticas, migra cada vinculación de origen y verifica la revisión y las credenciales sustitutas.

Continúa con Builds de Docker desde Git, Despliegues de Pages desde Git y Registros de contenedores. Para otros tipos de conectores, vuelve a Integraciones.

Solución de problemas

Separa los fallos de autenticación, las denegaciones por la lista de permitidos, los repositorios no encontrados, la resolución de revisiones, la entrega de webhooks, la admisión en el Build Worker y los fallos de derechos del plan. Conserva los ID de petición del proveedor y el historial de Tasks de Opfield sin registrar tokens, claves privadas, variables ni Build Secrets.

Flujo de código para producción

Fija el origen de producción a una política de ramas revisada y a un commit exacto resuelto. Un nombre de rama es una entrada de selección; el digest del commit es la prueba inmutable de lo que se construyó. Confirma la raíz de la aplicación, el gestor de paquetes, el script de build, el directorio del artefacto, la plataforma de ejecución y la política de publicación o despliegue antes de activar las acciones automáticas. Mantén los Build Secrets separados de las variables de ejecución ordinarias y expón solo los valores necesarios durante la etapa de build.

Para Pages y los builds de Git gestionados, verifica la cadena completa: acceso al proveedor, descubrimiento del repositorio, resolución del commit, admisión en el Build Worker, obtención de las dependencias, creación del artefacto, política de vulnerabilidades cuando esté activada, identidad inmutable del artefacto, Tag de publicación o revisión de la carga de trabajo y estado de cara al cliente. Un webhook del proveedor o un clon del código correctos son solo el principio de esa cadena.

Caducidad y rotación de los tokens

Opfield registra cuándo caducan los tokens de los conectores de GitLab y los tokens personales de GitLab de los usuarios y los comprueba a diario.

Alertas: Opfield avisa 30 y 7 días antes de que caduque el token de un conector, un token personal de GitLab o la autorización de una integración conectada mediante OAuth, siempre que se conozca la caducidad. GitLab informa de la caducidad de sus tokens; los tokens de GitHub y de Git genérico quedan cubiertos cuando se conectan mediante OAuth.
Autorrotación en GitLab: 14 días antes de la caducidad, Opfield rota los tokens de los conectores de GitLab y los tokens personales de GitLab que tienen el ámbito api o self_rotate. El nuevo token conserva la vida útil anterior, entre 30 días y un año, y sustituye al secreto guardado; la rotación se audita. Los access tokens de proyecto y de grupo no pueden rotarse a sí mismos por esta vía y solo reciben alertas.
Tokens caducados: Opfield deja de usar un token en cuanto caduca. Un token personal de GitLab caducado falla con GIT_CREDENTIAL_EXPIRED (HTTP 428), así que el usuario debe autorizar uno nuevo; un token de conector de GitLab caducado falla con CONNECTOR_TOKEN_EXPIRED (HTTP 409). Sustituir un token de conector caducado no requiere el anterior.

Las sincronizaciones, los orígenes de Docker y los builds de Pages que dependen de un token caducado dejan de funcionar hasta que se sustituye, así que trata la alerta de 30 días como el plazo de rotación de los tokens que Opfield no puede rotar por sí mismo.

Rotación, migración y eliminación

Para rotar credenciales, añade la sustituta al proveedor y a Opfield, verifica el descubrimiento y un build real y revoca después el valor anterior. Para migrar de proveedor o de repositorio, congela los despliegues automáticos, registra el último commit aprobado y el digest del artefacto, configura el origen sustituto, compara el árbol resuelto, ejecuta un build canario y mueve explícitamente el puntero de producción solo después de la verificación.

Antes de eliminar un conector, enumera todas las dependencias de Docker, Compose, Pages, registros, webhooks y automatización. Desactiva primero los desencadenantes. Los artefactos inmutables existentes pueden seguir funcionando, pero los builds futuros, las actualizaciones o la recuperación basada en el código pueden fallar cuando desaparezca el conector. Conserva el último artefacto aprobado y las instrucciones de reversión hasta que el nuevo camino de código haya superado un ciclo operativo.

Revisión de seguridad

Revisa los logs de auditoría del proveedor, los permisos de las aplicaciones instaladas, las deploy keys, las claves de host SSH, los secretos de los webhooks, las organizaciones y los repositorios permitidos y las vinculaciones inactivas. El acceso de lectura a un repositorio puede exponer código fuente y configuración propietarios; los permisos de escritura o de workflows pueden afectar a la cadena de suministro de software. Concédelos solo cuando el flujo de trabajo de Opfield seleccionado los requiera.

La revisión de los repositorios, las ramas protegidas, la política de dependencias y la aprobación de los artefactos siguen en tu proveedor de Git y en tu proceso de revisión. Opfield construye y despliega sobre ellos, con ámbitos y auditoría, y sigue tu política de código en lugar de saltársela.