Versionar imágenes Docker con tags es una práctica esencial para saber exactamente qué versión de una aplicación estás ejecutando, probando o desplegando. Un tag no es solo una etiqueta bonita: es una referencia que te ayuda a controlar cambios, hacer rollback y evitar sorpresas entre entornos.
El error habitual es depender siempre de latest. Puede funcionar en pruebas rápidas, pero en proyectos reales hace más difícil reproducir errores, auditar despliegues o saber qué imagen llegó a producción. Por eso conviene definir una estrategia clara de etiquetas.
En esta lección vas a aprender cómo versionar imágenes Docker con tags, qué formatos usar, cómo etiquetar imágenes ya construidas y qué buenas prácticas aplicar para trabajar con registros y pipelines de forma más segura.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Qué es un tag en una imagen Docker
Un tag es la parte final del nombre de una imagen y normalmente identifica una versión, variante o estado. En una referencia como mi-app:1.4.2, el repositorio es mi-app y el tag es 1.4.2.
docker image ls
docker pull nginx:1.27-alpine
docker pull nginx:stableDocker permite usar distintos tags para la misma imagen o para variantes diferentes. Algunos tags apuntan a versiones concretas; otros, como stable o latest, pueden moverse con el tiempo. Esa diferencia es clave al diseñar una estrategia de despliegue.
| Tipo de tag | Ejemplo | Uso recomendado |
|---|---|---|
| Versión semántica | 1.4.2 | Releases estables y reproducibles. |
| Versión mayor o menor | 1 / 1.4 | Canales controlados con cierto margen de actualización. |
| Commit corto | a1b2c3d | Trazabilidad desde CI/CD hasta el código fuente. |
| Entorno | staging / prod | Solo como alias operativo, no como única fuente de verdad. |
| latest | latest | Pruebas rápidas; evitar como referencia principal en producción. |
Cómo versionar imágenes Docker al construir
La forma más directa de asignar un tag es usar la opción -t durante el build. Puedes crear una imagen con una versión clara desde el primer momento.
docker build -t mi-app:1.0.0 .
docker build -t mi-app:1.0.1 .
docker image ls mi-appEste patrón deja claro qué versión estás construyendo. Si además tu proyecto usa releases, puedes alinear el tag de la imagen con la versión del código o del paquete.
También puedes asignar varios tags a la misma construcción, por ejemplo una versión exacta y un alias de rama o entorno.
docker build -t mi-app:1.0.1 -t mi-app:stable .Esto no crea dos builds distintos: crea dos referencias hacia la imagen resultante. Úsalo con cuidado y evita que los alias oculten cuál es la versión exacta desplegada.
Etiquetar imágenes ya existentes
Si ya tienes una imagen local, puedes crear un nuevo tag con docker tag. Es útil antes de subir una imagen a un registry o cuando necesitas cambiar el nombre hacia un repositorio remoto.
docker tag mi-app:1.0.1 registry.example.com/mi-equipo/mi-app:1.0.1
docker tag mi-app:1.0.1 registry.example.com/mi-equipo/mi-app:stableEl comando docker tag no copia capas ni reconstruye la imagen. Solo crea una nueva referencia. Por eso es rápido, pero también exige disciplina: si mueves stable, asegúrate de que el equipo sabe qué versión representa ahora.
docker image inspect registry.example.com/mi-equipo/mi-app:1.0.1Inspeccionar la imagen ayuda a revisar metadatos, digest y configuración. Para trazabilidad fuerte en producción, el digest es incluso más preciso que un tag, porque identifica el contenido exacto de la imagen.
Subir tags a un registry
Para compartir una imagen, necesitas subirla a un registry como Docker Hub, GHCR, GitLab Registry, ECR, ACR o Artifact Registry. El nombre de la imagen debe incluir el repositorio correcto antes de hacer push.
docker login registry.example.com
docker push registry.example.com/mi-equipo/mi-app:1.0.1
docker push registry.example.com/mi-equipo/mi-app:stableEn entornos reales no conviene hacer login manual en servidores de producción si puedes usar un pipeline seguro. Las credenciales del registry deben gestionarse como secretos y no quedar escritas en scripts o logs.
Si publicas varios tags para la misma imagen, empuja cada tag que quieras tener disponible en el registry. Que exista localmente no significa que ya exista remotamente.
Estrategia de tags recomendada
Una estrategia práctica suele combinar un tag inmutable y uno o varios alias móviles. El tag inmutable te da trazabilidad; el alias móvil facilita operaciones humanas.
mi-app:1.4.2
mi-app:1.4
mi-app:1
mi-app:sha-a1b2c3d
mi-app:stagingPara producción, la referencia más segura suele ser una versión concreta o un digest. Para entornos de desarrollo o staging, puedes permitir alias móviles si el equipo entiende que pueden cambiar.
- Usa tags inmutables para releases y despliegues que deban poder reproducirse.
- Usa el commit SHA cuando necesites conectar una imagen con una ejecución de CI/CD.
- Usa alias móviles solo como comodidad operativa, no como única trazabilidad.
- Evita latest como referencia principal de producción.
- Documenta la política para que todo el equipo etiquete igual.
Errores comunes al usar tags
- Creer que latest significa última versión estable: latest solo es un tag más y puede apuntar a lo que el publicador decida.
- Sobrescribir tags sin control: mover una etiqueta usada por producción rompe la reproducibilidad.
- No subir todos los tags necesarios: etiquetar localmente no publica automáticamente en el registry.
- No conectar tag y código fuente: sin versión, commit o release, es difícil saber qué contiene una imagen.
- Usar nombres distintos en cada equipo: una convención inconsistente complica despliegues y soporte.
El problema de fondo es tratar los tags como algo improvisado. Cuando empiezan los despliegues, los rollbacks y los incidentes, la estrategia de versionado deja de ser un detalle y se convierte en una herramienta de diagnóstico.
Buenas prácticas para versionar imágenes Docker
Automatiza el etiquetado en CI/CD. El pipeline puede generar tags a partir de la versión del proyecto, el commit y la rama. Así reduces errores manuales y mantienes una relación clara entre código, build e imagen.
No cambies tags inmutables una vez publicados. Si la versión 1.4.2 ya fue subida, corregir un fallo debería producir una nueva versión, no reemplazar silenciosamente el contenido anterior con el mismo nombre.
Usa digests cuando necesites máxima precisión. Un tag puede moverse, pero un digest identifica el contenido exacto. En auditorías, entornos críticos o investigaciones de incidentes, esta diferencia importa.
En resumen, versionar imágenes Docker correctamente te ayuda a desplegar con más control, reproducir errores y hacer rollback sin depender de suposiciones. La clave es combinar tags legibles, trazabilidad desde CI/CD y una política clara para no mover referencias críticas sin control.
Lecciones relacionadas del curso Docker
- Guía completa de Docker
- Imágenes de Docker
- Comandos Docker
- Docker Hub
- Qué es un Docker registry
- Dockerfile
Documentación oficial y recursos
- Referencia oficial de docker image tag
- Referencia oficial de docker image push
- Gestión de tags en Docker Hub
- Docker Build en CI
Con esta base, ya puedes definir una convención de tags más fiable: versiones exactas para releases, identificadores de commit para trazabilidad y alias móviles solo cuando estén documentados y controlados.

