Set up automated builds

Warning

Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

Note

Automated builds require a Docker Pro, Team, or Business subscription.

Configurar builds automáticas

Puedes configurar repositorios en Docker Hub para que compilen automáticamente una imagen cada vez que envíes nuevo código a tu proveedor de origen. Si tienes pruebas automatizadas configuradas, la nueva imagen solo se subirá cuando las pruebas tengan éxito.

1. En Docker Hub, ve a My Hub > Repositories y selecciona un repositorio para ver sus detalles.

2. Selecciona la pestaña Builds.

3. Selecciona GitHub o Bitbucket para conectar el lugar donde está almacenado el código fuente de la imagen.

   Note

   Es posible que se te redirija a la página de configuración para vincular el servicio de repositorio de código. De lo contrario, si estás editando la configuración de compilación de una build automática existente, selecciona Configure automated builds.

4. Selecciona el repositorio de origen (source repository) desde el que compilar las imágenes de Docker.

   Note

   Es posible que debas especificar una organización o usuario del proveedor de código fuente. Una vez que selecciones un usuario, los repositorios de código fuente aparecerán en la lista desplegable Select repository.

5. Opcional. Habilita las autotests.

6. Revisa las Build Rules (reglas de compilación) predeterminadas.

   Las reglas de compilación controlan lo que Docker Hub compila en imágenes a partir del contenido del repositorio de código fuente, y cómo se etiquetan las imágenes resultantes dentro del repositorio de Docker.

   Se configura una regla de compilación predeterminada para ti, la cual puedes editar o eliminar. Esta regla predeterminada establece compilaciones a partir de la Branch (rama) en tu repositorio de código fuente llamada master o main, y crea una imagen de Docker etiquetada como latest. Para más información, consulta configurar reglas de compilación.

7. Opcional. Selecciona el icono más (+) para agregar y configurar más reglas de compilación.

8. Para cada rama o etiqueta, habilita o deshabilita el interruptor Autobuild.

   Solo las ramas o etiquetas con autobuild habilitado se compilan, se prueban y su imagen resultante se sube al repositorio. Las ramas con autobuild deshabilitado se compilan con fines de prueba (si está habilitado a nivel de repositorio), pero la imagen de Docker compilada no se sube al repositorio.

9. Para cada rama o etiqueta, habilita o deshabilita el interruptor Build Caching.

   El almacenamiento en caché de compilación puede ahorrar tiempo si compilas una imagen grande con frecuencia o si tienes muchas dependencias. Deja el almacenamiento en caché de compilación deshabilitado para asegurarte de que todas tus dependencias se resuelvan en el momento de la compilación, o si tienes una capa grande que es más rápido compilar localmente.

10. Selecciona Save para guardar la configuración, o selecciona Save and build para guardar y ejecutar una prueba inicial.

    Note

    Se añade automáticamente un webhook a tu repositorio de código fuente para notificar a Docker Hub en cada envío. Solo los envíos a las ramas que están listadas como origen de una o más etiquetas activan una compilación.

Set up build rules

De forma predeterminada, cuando configuras las builds automáticas, se crea una regla de compilación básica para ti. Esta regla predeterminada busca cambios en la rama master o main en tu repositorio de código fuente y compila la rama master o main en una imagen de Docker etiquetada como latest.

En la sección Build Rules, introduce uno o más orígenes para compilar.

Para cada origen:

• Selecciona el Source type para compilar ya sea una etiqueta o una rama. Esto le indica al sistema de compilación qué buscar en el repositorio de código fuente.

• Introduce el nombre de la rama o etiqueta de Source (origen) que quieres compilar.

  La primera vez que configures las builds automáticas, se configura una regla de compilación predeterminada para ti. Este conjunto predeterminado compila desde la rama (Branch) de tu código fuente llamada master y crea una imagen de Docker etiquetada como latest.

  Puedes también usar una expresión regular (regex) para seleccionar qué ramas o etiquetas de origen compilar. Para más información, consulta expresiones regulares.

• Introduce la etiqueta que se aplicará a las imágenes de Docker compiladas a partir de este origen.

  Si configuraste una expresión regular para seleccionar el origen, puedes hacer referencia a los grupos de captura y usar su resultado como parte de la etiqueta. Para más información, consulta expresiones regulares.

• Especifica la Dockerfile location (ubicación del Dockerfile) como una ruta relativa a la raíz del repositorio de código fuente. Si el Dockerfile está en la raíz del repositorio, deja esta ruta establecida en /.

Note

Cuando Docker Hub descarga una rama de un repositorio de código fuente, realiza una clonación superficial (shallow clone): solo la punta de la rama especificada. Consulta opciones avanzadas para autobuild y autotest para obtener más información.

Variables de entorno para builds

Puedes establecer los valores de las variables de entorno utilizadas en tus procesos de compilación cuando configuras una build automática. Agrega tus variables de entorno de compilación seleccionando el icono más (+) junto a la sección Build environment variables y luego ingresando un nombre de variable y el valor.

Cuando estableces valores de variables desde la interfaz de usuario de Docker Hub, puedes usarlos en los comandos que configures en los archivos hooks. Sin embargo, se almacenan de modo que solo los usuarios que tienen acceso de administrador (admin) al repositorio de Docker Hub pueden ver sus valores. Esto significa que puedes usarlos para almacenar tokens de acceso u otra información que deba permanecer en secreto.

Note

Las variables configuradas en la pantalla de configuración de compilación se utilizan únicamente durante los procesos de compilación y no deben confundirse con los valores de entorno utilizados por tu servicio, por ejemplo para crear enlaces de servicio.

Opciones avanzadas de builds automáticas

Como mínimo, necesitas una regla de compilación compuesta por una rama u etiqueta de origen y una etiqueta de Docker de destino para configurar una build automática. También puedes:

• Cambiar dónde busca la compilación el Dockerfile
• Establecer una ruta para los archivos que la compilación debe usar (el contexto de compilación)
• Configurar múltiples etiquetas o ramas estáticas desde las que compilar
• Usar expresiones regulares (regexes) para seleccionar dinámicamente el código fuente a compilar y crear etiquetas dinámicas

Todas estas opciones están disponibles desde la pantalla de configuración de compilación para cada repositorio. En Docker Hub, selecciona My Hub > Repositories y selecciona el nombre del repositorio que quieres editar. Selecciona la pestaña Builds y luego selecciona Configure automated builds.

Builds de etiquetas y ramas

Puedes configurar tus builds automáticas para que los envíos a ramas o etiquetas específicas activen una compilación.

1. En la sección Build Rules, selecciona el icono más (+) para agregar más orígenes para compilar.

2. Selecciona el Source type para compilar una etiqueta o una rama.

   Note

   Esto le indica al sistema de compilación qué tipo de origen buscar en el repositorio de código.

3. Introduce el nombre de la rama o etiqueta de Source que quieres compilar.

   Note

   Puedes introducir un nombre o usar una expresión regular para que coincida con las ramas o etiquetas de origen que quieres compilar. Para más información, consulta expresiones regulares.

4. Introduce la etiqueta que se aplicará a las imágenes de Docker compiladas a partir de este origen.

   Note

   Si configuraste una expresión regular para seleccionar el origen, puedes hacer referencia a los grupos de captura y usar su resultado como parte de la etiqueta. Para más información, consulta expresiones regulares.

5. Repite los pasos del 2 al 4 para cada nueva regla de compilación que configures.

Establecer el contexto de compilación y la ubicación del Dockerfile

Dependiendo de cómo organices los archivos en tu repositorio de código fuente, los archivos requeridos para compilar tus imágenes pueden no estar en la raíz del repositorio. Si ese es el caso, puedes especificar una ruta donde la compilación buscará los archivos.

El contexto de compilación es la ruta a los archivos necesarios para la compilación, relativa a la raíz del repositorio. Introduce la ruta a estos archivos en el campo Build context. Introduce / para establecer el contexto de compilación como la raíz del repositorio de código fuente.

Note

Si eliminas la ruta predeterminada / del campo Build context y lo dejas en blanco, el sistema de compilación utilizará la ruta al Dockerfile como contexto de compilación. Sin embargo, para evitar confusiones, se recomienda que especifiques la ruta completa.

Puedes especificar la Dockerfile location como una ruta relativa al contexto de compilación. Si el Dockerfile está en la raíz de la ruta del contexto de compilación, deja la ruta del Dockerfile establecida en /. Si el campo del contexto de compilación está en blanco, establece la ruta al Dockerfile desde la raíz del repositorio de origen.

Expresiones regulares y builds automáticas

Puedes especificar una expresión regular (regex) para que solo se compilen las ramas o etiquetas que coincidan. También puedes usar los resultados de la expresión regular para crear la etiqueta de Docker que se aplica a la imagen compilada.

Puedes usar hasta nueve grupos de captura de expresiones regulares, o expresiones encerradas entre paréntesis, para seleccionar un origen para compilar, y hacer referencia a ellos en el campo Docker Tag utilizando desde {\1} hasta {\9}.

Compilar imágenes con BuildKit

Las autobuilds utilizan el sistema de compilación BuildKit de forma predeterminada. Si quieres utilizar el sistema de compilación de Docker heredado, añade la variable de entorno DOCKER_BUILDKIT=0. Consulta la página de BuildKit para más información sobre BuildKit.

Autobuild para equipos

Cuando creas un repositorio de compilación automática en tu propia cuenta de usuario, puedes iniciar, cancelar y reintentar builds, y editar y eliminar tus propios repositorios.

Estas mismas acciones también están disponibles para los repositorios de equipo desde Docker Hub si eres un propietario. Si eres miembro de un equipo con permisos de escritura (write), puedes iniciar, cancelar y reintentar builds en los repositorios de tu equipo, pero no puedes editar la configuración del repositorio de equipo ni eliminar los repositorios de equipo. Si tu cuenta de usuario tiene permisos de lectura (read), o si eres miembro de un equipo con permisos de lectura, puedes ver la configuración de compilación, incluidos los ajustes de prueba.

Usuarios de servicio para autobuilds de equipo

Note

Solo los propietarios pueden configurar builds automáticas para equipos.

Cuando configuras builds automáticas para equipos, otorgas a Docker Hub acceso a tus repositorios de código fuente mediante OAuth vinculado a una cuenta de usuario específica. Esto significa que Docker Hub tiene acceso a todo lo que la cuenta del proveedor de origen vinculada pueda acceder.

Para organizaciones y equipos, se recomienda crear una cuenta de servicio dedicada para otorgar acceso al proveedor de origen. Esto garantiza que ninguna compilación se interrumpa a medida que cambian los permisos de acceso de los usuarios individuales, y que los proyectos personales de un usuario individual no queden expuestos a toda una organización.

Esta cuenta de servicio debe tener acceso a cualquier repositorio que se vaya a compilar y debe tener acceso administrativo a los repositorios de código fuente para que pueda gestionar las claves de despliegue (deploy keys). Si es necesario, puedes limitar esta cuenta a solo un conjunto específico de repositorios requeridos para una compilación específica.

Si estás compilando repositorios con submódulos privados vinculados (dependencias privadas), también necesitas agregar una variable de entorno de anulación SSH_PRIVATE a las builds automáticas asociadas con la cuenta. Para más información, consulta Solución de problemas.

1. Crea una cuenta de usuario de servicio en tu proveedor de origen y genera claves SSH para ella.

2. Crea un equipo de "compilación" (build) en tu organización.

3. Asegúrate de que el nuevo equipo de "compilación" tenga acceso a cada repositorio y submódulo que necesites compilar.

   1. En GitHub o Bitbucket, ve a la página Settings del repositorio.

   2. Agrega el nuevo equipo de "compilación" a la lista de usuarios aprobados.

      • GitHub: Agrega el equipo en Collaborators and Teams.
      • Bitbucket: Agrega el equipo en Access management.

4. Agrega el usuario de servicio al equipo de "compilación" en el proveedor de origen.

5. Inicia sesión en Docker Hub como propietario, cambia a la organización y sigue las instrucciones para vincular al repositorio de código fuente usando la cuenta de servicio.

   Note

   Es posible que debas cerrar sesión en tu cuenta individual en el proveedor de código fuente para crear el enlace a la cuenta de servicio.

6. Opcional. Usa las claves SSH que generaste para configurar cualquier compilación con submódulos privados, utilizando la cuenta de servicio y las instrucciones anteriores.

¿Qué sigue?

• Personalizar tu proceso de compilación con variables de entorno, hooks y más
• Añadir pruebas automatizadas
• Gestionar tus builds
• Solución de problemas