Orígenes Git y Build Workers

Configura el conector con Hosting de Git. Esa guía también separa los permisos sobre los repositorios de los permisos sobre el destino necesarios para iniciar builds guardados y leer su historial. Las credenciales de los registros se tratan en Registros de contenedores.

La compatibilidad con orígenes Git conecta una revisión aprobada de un repositorio con un artefacto de build inmutable. Puede alimentar un Container Docker, un Deployment, un Compose Project o una versión de Pages, pero la carga de trabajo resultante sigue el ciclo de vida de su recurso propietario. Una conexión de origen no es, por sí sola, permiso para cambiar una Route de producción ni un destino de tráfico.

Decide qué puede hacer la automatización

Separa tres decisiones: quién puede leer el código, qué se considera un artefacto aprobado y si ese artefacto puede desplegarse automáticamente. Mantenerlas separadas permite a un equipo automatizar las versiones rutinarias sin dar a un webhook de repositorio una autoridad ilimitada sobre producción.

El responsable del código controla el acceso al repositorio y el commit que se construye. El responsable de la plataforma controla el Build Worker, la política de build, el registro y el destino del despliegue. El responsable del servicio define la aceptación y la reversión. Opfield conecta estos registros y conserva la procedencia desde el commit hasta el digest, pero un build correcto sigue siendo solo una entrada para una versión.

Usa el build automático cuando cada cambio de código seleccionado deba producir un artefacto. Activa el despliegue automático solo cuando el recurso propietario tenga una puerta de estado y un camino de recuperación probados, y solo para las ramas cuyo modelo de control de cambios lo permita. Para los servicios de mayor riesgo, mantén la aprobación del artefacto y el despliegue como decisiones humanas separadas.

Requisitos previos y propiedad

Usa una integración de código compatible y en la lista de permitidos, y autoriza solo el acceso a repositorios necesario para el build. Selecciona una revisión exacta de la rama y confirma después que el Build Worker dedicado asignado está en línea. El worker ejecuta un build a la vez por defecto (Parallel jobs en su página de nodo, hasta 16), usa un estado aislado de BuildKit y containerd, aplica límites de recursos fijos, deniega los entitlements de build inseguros y limpia la caché entre trabajos. Un host de Build Worker necesita systemd.

Los builds en cola van a los Build Workers en el orden en que aparecen en la lista Nodes: el primer worker en línea recibe builds hasta que todos sus trabajos paralelos están ocupados, y después los recibe el siguiente. Arrastra un worker hacia arriba para darle preferencia, o al final para reservarlo para los excesos. El orden de la lista es: carpetas de primer nivel por posición; dentro de una carpeta, primero sus subcarpetas y después sus nodos; y, al final, los nodos que no están en ninguna carpeta. Un worker solo recibe builds de su propia plataforma (arquitectura).

Los Build Secrets están limitados al origen y se montan como secretos durante el build. No pongas credenciales en argumentos de build, referencias de imagen, URL de repositorios, configuración confirmada ni logs. El Build Worker es responsable del aislamiento de la ejecución; el registro guarda el artefacto producido; el nodo Docker de destino descarga y ejecuta después ese artefacto.

Construye y revisa el artefacto

1. Conecta la integración y elige el repositorio, la rama y la revisión prevista.
2. Configura la entrada del build y los secretos limitados al origen.
3. Inicia el build y sigue su Task desde la asignación del worker hasta la publicación del artefacto.
4. Revisa los logs con los datos ocultos, los hallazgos de vulnerabilidades, el resultado de la política, el commit de origen y el digest inmutable del artefacto.
5. Selecciona el digest aprobado en el flujo de trabajo del Container, el Deployment o Pages propietario.

Mientras se despliega un build en un Container, un Deployment o un Compose Project, Opfield bloquea ese destino: los cambios de ciclo de vida y de configuración, los cambios de secretos, los cambios de Availability y las migraciones se rechazan con BUILD_ROLLOUT_IN_PROGRESS hasta que el despliegue tiene éxito, falla o se cancela, y la consola muestra un aviso en el destino. El bloqueo sobrevive a un reinicio de Opfield. Si el destino está ocupado con otra operación cuando empieza el despliegue, el despliegue espera hasta 5 minutos y después falla con BUILD_ROLLOUT_TARGET_BUSY. Las versiones de Pages no se bloquean de esta forma. Durante una actualización de Opfield, los builds desencadenados por webhooks o por sondeo se aplazan y se inician una vez tras la actualización.

Sync now, en el origen Git de un Container, un Deployment, un Compose Project o un Pages Project, comprueba la rama de inmediato y construye cuando ha avanzado y los builds automáticos están activados. La política de vulnerabilidades del origen rechaza los artefactos con hallazgos de la severidad seleccionada o superior (Critical por defecto, o High, Medium o Low); None aprueba todos los artefactos analizados, y Disabled aprueba los artefactos sin exigir un análisis. Los resultados de los builds se envían al registro sin guardarse en el almacén de imágenes propio del worker, así que los builds no llenan el disco del worker.

El build automático y el despliegue automático son controles independientes. Mantén desactivado el despliegue automático hasta demostrar el camino de estado y de reversión de esa carga de trabajo. Un build correcto solo demuestra que existe un artefacto; no demuestra que la aplicación arranque correctamente en un nodo de destino.

Carpeta de las cargas de trabajo construidas

Un Container o un Deployment creados a partir de un origen Git van a la carpeta elegida al crearlos: el campo de carpeta de la pestaña Repository del diálogo de despliegue, o folderId a través de la API y de MCP. Crearlo allí requiere el permiso de creación sobre esa carpeta, y un usuario que solo puede crear en carpetas debe elegir una; el diálogo preselecciona la única carpeta permitida. Configurar el origen requiere además integrations:<provider>:use sobre el repositorio; consulta Hosting de Git.

Hasta que termine su primer build, la carga de trabajo aparece en esa carpeta con Awaiting build en lugar de una imagen. Se puede mover como cualquier otro contenedor: con Move to folder…, arrastrándola o a través de la API y de MCP, lo que requiere permiso de edición sobre la carga de trabajo y sobre el destino. El primer build la crea en la carpeta en la que esté en ese momento y comprueba allí el permiso de creación, también cuando es la automatización del origen la que inicia el build. Así, un usuario limitado a carpetas nunca termina con una carga de trabajo construida en la raíz. Mientras tanto, el nombre queda reservado para el origen: crear, duplicar, renombrar o importar otro contenedor con ese nombre falla con 409 NAME_IN_USE.

Gestión de fallos

Si un build no puede empezar, comprueba la autorización del origen, la disponibilidad del worker, el derecho del plan y el estado de la integración. Los builds usan la credencial del conector y no dependen de los ámbitos de Git que tenga nadie en ese momento: integrations:<provider>:use sobre el repositorio solo se necesita para conectar el origen o cambiar su conector, su repositorio o su rama; consulta ¿Quién puede hacer builds y ver los resultados?. Si falla después de empezar, usa la fase y los logs para distinguir fallos de dependencias, secretos, políticas, definición del build o publicación del artefacto. Corrige el código o la configuración del build y ejecuta un build nuevo. Reintentar produce una operación nueva y conserva el historial anterior.

Cuando el worker o la automatización del origen no están disponibles, el historial existente sigue siendo útil para el diagnóstico, pero no hay que suponer que los builds nuevos se ejecutarán. No sustituyas el artefacto inmutable que falta por un tag de imagen mutable; espera a un build verificado o usa una imagen aprobada por separado.

Preparación tras un despliegue

Cuando se despliega un build en un Container, Opfield lo recrea con la nueva imagen y espera hasta 60 segundos a que esté listo: en buen estado cuando la imagen tiene una comprobación de estado y, si no, en ejecución durante 10 segundos sin reiniciarse. Un contenedor que entra en un bucle de fallos, termina o pasa a estar en mal estado vuelve a su imagen anterior, y el build falla con BUILD_ROLLOUT_ROLLED_BACK, o con BUILD_ROLLOUT_ROLLBACK_FAILED cuando no se pudo restaurar la imagen anterior. El error indica el estado del contenedor, el código de salida y el número de reinicios, seguidos de las últimas líneas de su log, y el commit desplegado sigue siendo el anterior. Los demás fallos de despliegue se notifican como BUILD_ROLLOUT_FAILED. Un Deployment usa su propio camino blue/green con comprobación de estado: un candidato que falla se detiene y el tráfico se queda en el slot que sirve. Una revisión de Compose construida desde Git cuyo puerto publicado ya ocupa otra carga de trabajo en el nodo falla con COMPOSE_HOST_PORT_IN_USE, y no se crea ninguna revisión.

Limpieza y reversión

Eliminar una conexión de origen impide el trabajo futuro desencadenado por el código, pero no elimina automáticamente un entorno de ejecución ya desplegado ni su artefacto. Eliminar un contenedor elimina su origen Git, y cuando no se puede eliminar el webhook del repositorio de un contenedor eliminado, su origen deja de construir y desplegar, de modo que un commit nuevo no puede recrear el contenedor; la limpieza se reintenta más tarde. Las imágenes de build de los Containers, Deployments y Compose Projects eliminados se eliminan automáticamente de sus nodos, normalmente en menos de un minuto, y los nodos que estaban desconectados se vuelven a comprobar cada 10 minutos. Una imagen de build sin usar también se puede eliminar a mano desde las imágenes del nodo; si un contenedor del nodo todavía la usa, la eliminación se rechaza con 409 OPFIELD_INTERNAL_IMAGE. Antes de revocar la conexión, decide qué artefactos siguen siendo necesarios para una reversión. La retención de los artefactos depende del registro y del historial activo, de reversión, en curso, fijado y de éxitos recientes del recurso propietario.

Criterios de éxito

Un build aceptable identifica el repositorio y el commit exacto, termina en un worker aprobado, produce un digest inmutable, supera la política de vulnerabilidades configurada y expone logs sin secretos. La aceptación del despliegue es aparte: el recurso de destino debe descargar ese digest, arrancar correctamente, superar la verificación de estado y servir el camino de cliente esperado.

Conserva suficiente historial de builds y artefactos para explicar lo que se está ejecutando y para restaurar la versión anterior que se sabe que funciona. Un tag mutable, un log de consola correcto o una insignia de build en verde sin el digest no son pruebas suficientes para producción.

Detalles para operadores: aislamiento y diagnóstico

Los Build Workers son límites de ejecución dedicados porque el contenido de los repositorios y las definiciones de build pueden ejecutar código. Mantén restringidas las credenciales del worker, no coloques junto a él cargas de trabajo sensibles no relacionadas y trata la salida del build como no fiable hasta que terminen las comprobaciones de política y de procedencia. Los Build Secrets solo deben montarse en el paso de build que los necesita y nunca deben copiarse en las capas de la imagen.

Los pasos de build no pueden llegar al propio host del Build Worker, ni por IPv4 ni por IPv6, con ninguno de los dos perfiles de salida (internet u offline). En un host con IPv6, el worker necesita ip6tables y no arranca sin él.

Cuando un build está en cola, distingue la falta de capacidad de los workers de un fallo de origen o de política. Cuando se ejecuta y falla, identifica la fase: obtención del código, resolución de dependencias, build del Dockerfile o de Compose, admisión de vulnerabilidades, publicación en el registro o confirmación final. Conserva el log acotado y el commit antes de reintentar. Un reintento debe crear un intento nuevo y auditable en lugar de sobrescribir el registro fallido.