Despliegues de Pages desde Git

Conecta y restringe primero el repositorio con Hosting de Git. El acceso del conector, los permisos de despliegue de Pages y el permiso para ver el historial de builds son comprobaciones separadas.

Un despliegue de Pages desde Git convierte una revisión seleccionada del repositorio en un nuevo despliegue inmutable de un sitio estático. El origen Git y el Build Worker producen el artefacto; el Pages Project es responsable del historial de despliegues publicados; los Tags y las Routes controlan cuándo llega ese artefacto a los usuarios.

Decide si un build correcto solo crea un candidato para revisión o si además mueve automáticamente un Tag de publicación. Mantén la publicación manual hasta que la vista previa, la verificación y la reversión funcionen para el sitio. Un build en verde demuestra que se produjo un artefacto; no demuestra que el dominio público, la Route TLS o el comportamiento en el cliente sean correctos.

Los builds de Pages desde Git requieren un plan Business o Enterprise. Las subidas manuales de sitios estáticos funcionan en Personal y superiores. Ambos usan los mismos despliegues inmutables, así que la verificación, la publicación y la reversión funcionan igual.

Antes de empezar

Conecta una integración de Git compatible y elige un repositorio y una rama que la integración pueda leer. Confirma que hay un Build Worker dedicado en línea, que el proyecto tiene la definición de build correcta y que los Build Secrets necesarios, limitados al origen, están disponibles. Los Build Secrets son para el límite aislado del build; la configuración de ejecución es pública y no debe contener esos secretos.

Revisa el package.json del repositorio cuando se use para descubrir el build, elige el gestor de paquetes y el comando de build adecuados y asegúrate de que la salida es un artefacto de sitio estático. Un despliegue desde Git no hace disponible un entorno de ejecución de aplicaciones del lado del servidor a través de Pages.

El conector solo debe tener acceso de lectura a los repositorios seleccionados. El Build Worker necesita capacidad suficiente para instalar dependencias y hacer el build estático, pero no debe compartir un espacio de trabajo mutable con las cargas de trabajo de producción. Los Build Secrets limitados al origen solo están disponibles dentro del límite aislado del build y nunca deben copiarse en los archivos estáticos generados ni en la configuración de ejecución pública.

Define el éxito antes de activar la automatización

Registra la rama esperada, la raíz de la aplicación, el gestor de paquetes, la versión de Node.js, el script de build, el directorio del artefacto, el Tag de publicación y el responsable. Después define la comprobación de aceptación del sitio producido: el documento de entrada esperado, el comportamiento de la navegación directa, la carga de los recursos, los metadatos, las rutas por idioma, el sitemap o el índice de búsqueda cuando corresponda y la ausencia de secretos en el artefacto.

Activa los builds automáticos cuando cada actualización relevante del código deba producir un candidato. Activa el despliegue automático solo cuando cada candidato correcto pueda mover con seguridad el Tag configurado. Para los sitios de documentación y de marketing, el build automático con promoción explícita a producción permite revisar primero la vista previa inmutable. 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?.

Construye un despliegue

1. Selecciona el repositorio, la rama y la revisión prevista para el Pages Project.
2. Configura el descubrimiento del build, el gestor de paquetes, el comando de build y los Build Secrets limitados al origen.
3. Inicia el build y sigue la operación en su Build Worker aislado asignado.
4. Revisa el log del build con los datos ocultos, el resultado de la política, la revisión del código y la salida inmutable.
5. Crea o selecciona el despliegue resultante y pruébalo antes de mover un Tag de producción.

El build está separado intencionadamente de la publicación. Un build completado crea un despliegue inmutable candidato; no cambia un Tag personalizado ni una Route. El build automático y el despliegue automático deben tratarse como controles independientes, y el despliegue automático solo debe activarse cuando se entienda el camino de estado, promoción y reversión.

Promueve y verifica

Mueve el Tag previsto al despliegue aprobado. Las Routes apuntan a ese Tag, así que el movimiento es el evento de promoción. Verifica el comportamiento DNS y TLS del dominio público, el documento y los recursos estáticos devueltos, el window.runtime.config visible para el cliente y el estado de la operación del proyecto. Usa una vista previa inmutable, cuando esté configurada, para inspeccionar un artefacto concreto sin mover un Tag público.

Mantén disponible un despliegue anterior que se sepa que funciona durante la ventana de reversión. La configuración de ejecución debe seguir siendo compatible mientras el mismo Tag pueda seleccionar cualquiera de las dos versiones: cambiarla puede alterar el comportamiento del sitio sin crear un despliegue nuevo ni cambiar los hashes del artefacto.

Build fallido, cancelación y reversión

Un build fallido o cancelado no debe cambiar la versión pública activa. Inspecciona la asignación del worker y los logs para distinguir fallos de autorización del código, de dependencias, del comando de build, de Build Secrets, de políticas o de la salida del artefacto. Corrige la causa y reintenta; cada reintento crea una operación nueva en lugar de modificar el resultado histórico.

Durante una actualización de Opfield, los builds desencadenados por webhooks o por sondeo se aplazan y se inician una vez cuando termina la actualización.

Si una versión promovida provoca un incidente, devuelve el Tag de la Route al despliegue verificado anterior. Después verifica la respuesta de la Route, los recursos, la configuración de ejecución y el estado aplicado en nginx. No edites ni sustituyas en su sitio el despliegue fallido: su registro inmutable es importante para el diagnóstico y como prueba de la reversión.

Detalles para operadores: clasificación de los fallos de build

Clasifica el fallo antes de reintentar:

Área del fallo	Prueba habitual	Siguiente acción segura
Autorización del código	No se puede leer el repositorio o la revisión	Repara los permisos del conector; no amplíes por defecto el acceso a toda la organización
Instalación de dependencias	Error del lockfile, del registro o del gestor de paquetes	Reprodúcelo con el mismo gestor de paquetes y el mismo lockfile; verifica solo el secreto de registro necesario
Comando de build	El script termina con un código distinto de cero o falta la salida del framework	Corrige el build del repositorio y conserva el trabajo fallido para compararlo
Contrato del artefacto	El directorio de salida falta, está vacío o no es estático	Corrige el directorio del artefacto o la salida del build; no publiques un directorio parcial
Política o admisión	Build rechazado antes de la publicación	Resuelve el hallazgo de política notificado u obtén una excepción aprobada explícitamente
Publicación	El despliegue existe, pero el Tag o la Route no se movieron	Inspecciona los ajustes de despliegue automático y la operación de Pages; no reconstruyas un artefacto válido

La cancelación detiene la operación de build activa, pero no elimina los despliegues anteriores ni mueve un Tag de producción existente. Reintentar un build conserva el SHA de commit exacto del build original, lo que hace que el reintento sea reproducible aunque la rama configurada haya avanzado. Inicia un build nuevo desde el código cuando la nueva cabeza de la rama sea la entrada prevista.

Versiones manuales y limpieza

Una versión manual de Pages sigue el mismo modelo de promoción: crea un despliegue inmutable nuevo a partir del artefacto estático preparado, verifícalo y mueve un Tag solo cuando esté listo. El historial de Git es útil para la procedencia, pero no es necesario para que un artefacto manual participe en el mismo ciclo de vida de Tags y Routes.

Al desconectar un origen Git, decide qué despliegues existentes siguen siendo necesarios para la reversión. Eliminar el origen detiene los builds futuros desencadenados por el código; no despublica automáticamente un Tag existente ni elimina un artefacto desplegado. Revisa las referencias de los Tags y la retención antes de eliminar cualquier despliegue.

En los repositorios sensibles, revisa los logs de build antes de compartirlos. Opfield oculta los Build Secrets gestionados, pero los scripts de build pueden seguir imprimiendo contenido del repositorio o derivar valores sensibles. Trata la definición del build como código de producción y mantén los secretos fuera de los comandos, los nombres de archivo, los manifiestos generados y los bundles del cliente.