Verificando autenticación…

Saltar al contenido principal

Versionado Semántico en los pipelines ANDES

Los pipelines ANDES DX versionan tu aplicación automáticamente en cada pipeline. No necesitas crear tags ni escribir versiones manualmente: el pipeline lo hace por ti siguiendo Semantic Versioning 2.0.0.

Esta guía es para desarrolladores que usan los pipelines estándar por lenguaje (golang-service, java-service, react-service, python-service).

¿Usas los componentes directamente para armar tu propio pipeline? Revisa la Referencia técnica del componente code/version.

Qué ocurre en cada pipeline​

Cada merge a main produce un Release Candidate (RC). Cuando decides que ese RC está listo para producción, corres el pipeline con el input release_candidate y se crea la versión stable.

Los dos momentos del ciclo de versión​

1. Merge a main → Release Candidate​

Cada vez que un MR se fusiona a main, el pipeline:

  1. Lee la versión declarada en tu proyecto.
  2. Genera un tag Git con sufijo -rc.<número_de_pipeline> — por ejemplo 1.4.2-rc.314.
  3. Publica la imagen en el registry interno con ese tag.
  4. Registra el release en GitLab.

Este RC es interno — no llega a producción automáticamente.

¿Dónde queda la imagen?

Las imágenes RC se publican en el registry interno de GitLab del proyecto. Las imágenes stable se promueven al registry definitivo. Ver Imágenes Docker para los registries disponibles.

2. Pipeline con release_candidate → Versión stable​

Cuando el RC está validado y quieres liberar a producción:

  1. Ve a GitLab → CI/CD → Run pipeline en la rama main.
  2. Agrega la variable release_candidate con el ticket Jira del cambio — por ejemplo ANDES-1234. El ticket es el trazador entre el release técnico y la decisión de negocio que lo autoriza. El proceso completo se describe en Pase a producción.
  3. Corre el pipeline.

El pipeline:

  1. Promueve la imagen del registry interno al registro definitivo.
  2. Crea el tag stable en Git — por ejemplo 1.4.2 (o v1.4.2 en proyectos Go).
  3. Publica el release en GitLab con las notas del CHANGELOG.md.
  4. Elimina todos los tags RC de esa versión (1.4.2-rc.*).
El ticket Jira no es opcional

Sin un ticket válido en release_candidate, el paso de promoción no se ejecuta y el pipeline falla. El formato esperado es PROYECTO-NNN — por ejemplo ANDES-1234.

Cómo sabe el pipeline cuál es tu versión​

El pipeline detecta la versión desde el archivo de tu proyecto según el lenguaje:

StackFuente principal
GoTags Git estables en el commit → CHANGELOG.md
Javagradle.properties → pom.xml → build.gradle
React / Nodepackage.json (campo "version")
Pythonpyproject.toml → setup.cfg → setup.py

Esa versión base es el VERSION_CORE — por ejemplo 1.4.2. El pipeline le agrega el sufijo de canal (-rc.314) y los metadatos de build para formar la versión final.

Mantén la versión de tu proyecto actualizada

Si no actualizas el número de versión en tu manifiesto antes de liberar, el pipeline seguirá usando la misma versión base aunque el código haya cambiado. Actualiza la versión antes de hacer el merge que quieras convertir en stable.

Tags que produce el pipeline​

CanalEjemplo (Go)Ejemplo (otros stacks)
RCv1.4.2-rc.3141.4.2-rc.314
Stablev1.4.21.4.2

Los proyectos Go usan el prefijo v porque el sistema de módulos de Go lo requiere — go get y go mod resuelven versiones por tags Git y esperan el formato vX.Y.Z. El pipeline golang-service lo activa automáticamente.

Cuando liberas un stable, la imagen en el registry también recibe tags de alias si es la versión más alta en su serie: 1.4.2, 1.4 y 1. Esto permite que otros servicios usen :1.4 sin actualizar su referencia con cada patch.

Reglas importantes​

No crees tags de versión manualmente​

peligro

Crear un tag Git con formato SemVer (1.2.3 o v1.2.3) fuera del pipeline puede hacer que el próximo pipeline falle por colisión de versión. Toda gestión de tags la hace el pipeline.

El CHANGELOG.md debe tener una entrada para tu versión​

En ramas main y MRs que apunten a main, el pipeline valida que CHANGELOG.md tenga una entrada ## [X.Y.Z] con contenido para el VERSION_CORE actual. Si no existe o está vacía, el pipeline falla antes de publicar nada.

Un encabezado vacío también falla — la entrada debe tener al menos una línea de contenido.

Una versión stable es permanente​

Una vez creado el tag stable 1.4.2, esa versión queda bloqueada para ese commit. Si necesitas corregir algo en producción:

  1. Corrige en main.
  2. Incrementa la versión en tu manifiesto (1.4.2 → 1.4.3).
  3. Haz el merge → se genera 1.4.3-rc.N → luego liberas 1.4.3.

Preguntas frecuentes​

¿Qué pasa si re-ejecuto el pipeline en el mismo commit?

El pipeline detecta que el tag RC ya existe en ese commit y no crea uno nuevo — la ejecución es idempotente. Si el tag RC existe en un commit diferente, el pipeline falla para evitar colisión.

¿Puedo tener 1.4.2-rc.N y 1.5.0-rc.N al mismo tiempo?

Sí. Cada VERSION_CORE es independiente. Los RC de versiones anteriores siguen existiendo hasta que liberes su stable correspondiente.

¿El RC llega a producción automáticamente?

No. El RC queda en el registry interno. Solo el stable llega al registry definitivo de producción. Ver Pase a producción.

¿Puedo sobreescribir la versión detectada?

Sí, con el input package_version. Ver Uso directo del componente.

Siguiente paso​

Cuando tu RC esté validado, sigue el proceso de Pase a producción para gestionar el cambio y liberar la versión stable.