De Git a producción

La entrega basada en Git conecta una revisión de código revisada con un artefacto inmutable y después con el ciclo de vida de un recurso propietario de Opfield. La integración de código demuestra qué se puede leer, el Build Worker es responsable de la ejecución aislada, el registro guarda el artefacto y el Container, Deployment, Compose Project o Pages Project decide si ese artefacto llega a los usuarios.

El permiso para construir un repositorio no es permiso para cambiar una Route de producción, y un build correcto todavía no es un despliegue correcto.

Los builds desde Git y el push-to-deploy para Containers, Deployments, Compose Projects y Pages requieren Business o Enterprise; consulta Planes y derechos.

Antes de empezar, prepara la integración de control de código fuente y el Build Worker. Para un sitio estático, revisa también los despliegues de Pages desde Git.

Define la propiedad y la política de versiones

Acuerda estas decisiones antes de conectar el código de producción:

• qué integración e identidad de repositorio puede usar Opfield;
• qué repositorios y ramas están en la lista de permitidos;
• quién puede editar los ajustes de origen y los Build Secrets;
• si los pushes desencadenan builds automáticamente;
• si un build aprobado puede desplegarse automáticamente o requiere promoción;
• qué política de vulnerabilidades bloquea un artefacto;
• qué comprobaciones exactas de cara al usuario definen un despliegue correcto;
• quién puede revertir o cancelar una operación en curso.

Mantén separados el build automático y el despliegue automático. El build automático crea un artefacto candidato. El despliegue automático cambia un recurso en ejecución o un Tag de Pages y, por tanto, conlleva un riesgo distinto.

Prepara el límite de ejecución

Configura una integración compatible de GitLab, GitHub, Git genérico o External SSH en Settings > Integrations. Concede al conector solo el acceso a repositorios necesario para el descubrimiento y la clonación. No incluyas credenciales en las URL de los repositorios.

Registra un Build Worker dedicado y verifica que está Online e informa de las capacidades de ejecución, de entorno de ejecución dedicado y de aplicación de recursos necesarias para la admisión de builds. Un Build Worker usa servicios BuildKit/containerd dedicados y no expone un socket ordinario de Docker Engine al perfil de build.

Trata el host externo del Build Worker o el contenedor de sistema sin privilegios como el límite de seguridad. Procesa entradas controladas por el repositorio y no debe contener cargas de trabajo no relacionadas, credenciales de instancias en la nube, claves de despliegue ni secretos del plano de control. El perfil de salida de red configurado debe ajustarse al build: puede que haga falta descargar dependencias públicas, pero los rangos de metadatos, privados y del plano de control deben seguir denegados.

Conecta el recurso

1. Crea o abre el Container, Deployment, Compose Project o Pages Project de destino.
2. Selecciona el modo Repository y elige la integración, el repositorio y la rama aprobados.
3. Configura el contexto de build y el Dockerfile, o el archivo Compose acotado y los campos build compatibles. Para Pages, selecciona el descubrimiento del gestor de paquetes, el script de build, la versión de Node y el directorio del artefacto.
4. Añade Build Secrets limitados al origen solo cuando el build los necesite de verdad.
5. Decide por separado el build automático y el despliegue automático.
6. Guarda la configuración de origen y revisa la ruta del repositorio resuelta antes de desencadenar un candidato de producción.

Los Build Secrets se montan a través del mecanismo de secretos de BuildKit y se ocultan en los logs compatibles. No son argumentos de build ordinarios y nunca deben copiarse en ARG, ENV, archivos confirmados, etiquetas de imagen, URL del gestor de paquetes ni en trazas de la shell. Un secreto usado durante el build puede filtrarse igualmente a través de un Dockerfile malicioso, así que la revisión del repositorio sigue formando parte del límite.

Construye y aprueba un artefacto

Pon el build en cola y sigue su registro de trabajo duradero. Revisa:

• la rama resuelta y el commit exacto;
• el Build Worker asignado y la plataforma de destino;
• los logs del build con la ocultación de secretos esperada;
• los resultados de vulnerabilidades y de políticas;
• el digest inmutable o el artefacto de Pages producido;
• el estado de cancelado, reintentado o sustituido;
• el recurso propietario que consumirá el artefacto.

Un build solo se puede publicar cuando la decisión de su política está aprobada y el artefacto está disponible en el registro configurado o en el flujo de despliegue de Pages. No lo sustituyas por un tag de imagen mutable si una caída del worker o del registro impide crear el digest aprobado.

Comportamiento por lotes de Compose

Un archivo Compose de un repositorio puede crear un build hijo por cada servicio con una sección build compatible. Cada Build Worker ejecuta un build a la vez, así que un proyecto puede quedar en cola de forma secuencial cuando la capacidad es limitada.

Opfield espera a que se aprueben todos los artefactos hijos esperados antes de crear la revisión inmutable de Compose fijada por digest. Un hijo fallido, rechazado, cancelado o sustituido bloquea todo el despliegue. Es intencionado: aplicar una mezcla de imágenes de servicio antiguas y nuevas haría que la revisión del código y la revisión en ejecución no coincidieran.

Las redes solo de ejecución y las superposiciones de bases de datos gestionadas se pueden añadir a la revisión desplegada sin reescribir el código de Compose escrito. Revisa la revisión final en lugar de suponer que el archivo de origen describe todas las conexiones de ejecución propiedad de Opfield.

Despliega y verifica

Promueve el artefacto aprobado a través del ciclo de vida de su propietario:

• un Container usa una recreación controlada;
• un Deployment usa su despliegue blue/green con comprobación de estado;
• un Compose Project crea y aplica una revisión inmutable;
• un Pages Project crea un despliegue inmutable y mueve el Tag previsto.

Verifica el digest o el commit desplegado, el estado de ejecución, los logs, la Route pública y cualquier vinculación de base de datos. Para Pages, verifica el HTML devuelto, los recursos, la configuración de ejecución visible para el cliente y el Tag seleccionado. Para las cargas de trabajo Docker, confirma que el nodo de destino descargó el digest aprobado y no un tag con un nombre parecido.

Registra el último artefacto que se sabe que funciona antes de la promoción. Una reversión del código debe ser explícita: vuelve a desplegar el digest aprobado anterior o devuelve el Tag de Pages a su posición. Volver a construir más tarde la misma rama puede producir un candidato distinto si las dependencias han cambiado, así que no equivale a usar el artefacto que se sabe que funciona.

Fallos y recuperación

Falla el descubrimiento del código: comprueba la autorización del conector, la lista de repositorios permitidos, que la rama exista y la raíz de la aplicación. No amplíes la integración a toda una organización sin revisión.

Ningún worker acepta el trabajo: verifica el estado del worker y las capacidades necesarias, que se pueda escribir en el registro, el derecho del plan y la política de salida de red. Los despliegues existentes siguen siendo válidos; espera a tener capacidad de build segura en lugar de saltarte el camino del artefacto inmutable.

La política rechaza el artefacto: revisa los hallazgos y el umbral de la política. Corrígelo o cambia explícitamente la política a través del proceso de seguridad aprobado; no vuelvas a etiquetar el mismo digest como de confianza.

El despliegue falla tras un build correcto: conserva el registro del build. Diagnostica el recurso propietario, la comprobación de estado, la capacidad del nodo, los secretos y las dependencias externas. Un build correcto demuestra que se creó el artefacto, no que la ejecución sea correcta.

La entrega automática crea riesgo: desactiva primero el despliegue automático y mantén los builds automáticos si son útiles. Así se conserva la generación de candidatos sin cambiar producción con cada evento de código.

Mapa de diagnóstico

Síntoma	Comprueba primero	Guía detallada
No se descubre el repositorio	Autorización del conector, lista de repositorios permitidos, rama, raíz de la aplicación	Integraciones de control de código fuente
El Build Worker no acepta el trabajo	Estado del nodo, capacidades, plan, acceso de escritura al registro	Orígenes Git y Build Workers
Se rechaza el build	Hallazgos de la política y umbral de bloqueo en el registro del build	Orígenes Git y Build Workers
El artefacto existe pero el despliegue falla	Task del despliegue, nodo de destino, logs, comprobación de estado	Tasks, eventos y auditoría
No se puede descargar la imagen	Accesibilidad del registro, digest y credenciales guardadas	Registros y confianza en imágenes

Conserva el ID del build, el ID del Task, el commit exacto y el error antes de reintentar. Un build nuevo puede ocultar si el candidato anterior terminó, falló o sigue en ejecución.