Version: 1.0.0
Fecha: 7 de Septiembre, 2026
Estado: NORMATIVO - CI/CD
Arquitecto: Carlos Alberto Torres Camargo
Dirigido a: Equipo Frontend
Este documento fija como se publica nebula-ui-kit en Nexus: quien puede hacerlo, que
rama publica que cosa, como se numera cada version y que hay que cambiar en el repositorio
para que la siguiente publicacion salga con el numero correcto.
Hasta ahora el kit se publicaba a mano. Desde el 7 de septiembre de 2026 lo publica
Jenkins, y nadie ejecuta npm publish por su cuenta.
| Recurso | Valor |
|---|---|
| Repositorio | gitlab.centricasoluciones.com/nebula/frontend/nebula-ui-kit |
| Registro npm (Nexus) | https://nexus.centricasoluciones.com/repository/centrica-frontend/ |
| Job de Jenkins | Multibranch nebula-ui-kit |
| Pipeline | npmLibraryPipeline de la libreria compartida centrica-pipeline |
| Credencial de publicacion | nexus-npm-frontend (usuario centrica.ci) |
| Node del agente | Node 22 |
| Disparo | Webhook de GitLab por push events |
El Jenkinsfile del repositorio tiene doce lineas: toda la logica vive en la libreria
compartida, igual que en los 22+ repositorios de backend.
| dist-tag | Version | Que es |
|---|---|---|
latest |
0.16.0 | La estable. Es la que instala quien no pide una version concreta |
dev |
0.16.0-dev.2 | La ultima prerelease publicada desde develop |
La publicacion depende solo de la rama a la que integres.
| Rama | Que publica | dist-tag | Confirmacion |
|---|---|---|---|
develop |
X.Y.Z-dev.<build> |
dev |
Ninguna, es automatico |
main |
X.Y.Z |
latest |
Manual, alguien debe confirmarlo en Jenkins |
| Cualquier otra | Nada | — | Solo valida |
develop — el canal de pruebaCada integracion a develop publica una prerelease en cuanto Jenkins recibe el webhook.
El numero de build la hace unica: 0.17.0-dev.1, 0.17.0-dev.2, y asi sucesivamente.
Nadie confirma nada. Si integras, se publica.
Va con dist-tag dev, de modo que un npm install nebula-ui-kit corriente sigue trayendo
la estable. La prerelease solo llega a quien la pide.
main — el canal realUn merge a main construye, valida y se detiene con una pregunta en Jenkins:
¿Publicar nebula-ui-kit@0.17.0 a Nexus? [Publicar] [Abort]
Hasta que alguien pulse Publicar, no se sube nada. Al confirmar, esa version pasa a ser
latest y la reciben todos los proyectos que instalen el kit sin pedir version.
Por eso el paso es manual: publicar en main cambia lo que instala todo el mundo.
Se usa SemVer sobre la version declarada en:
projects/nebula-ui-kit/package.json
Es el
package.jsonde la libreria, no el de la raiz del workspace. El de la raiz
configura el proyecto Angular; el que viaja dentro del paquete publicado es el otro.
| Cambio | Que subir | Ejemplo |
|---|---|---|
| Correccion interna, sin cambiar la API publica | patch |
0.16.0 -> 0.16.1 |
| Componente o parametro nuevo, compatible hacia atras | minor |
0.16.0 -> 0.17.0 |
| Algo que rompe a quien ya usa el kit | major |
0.16.0 -> 1.0.0 |
La prerelease la calcula el pipeline, no se escribe a mano:
version de package.json + "-dev." + numero de build de Jenkins
Cuando prepares un cambio, sube la version en el mismo Merge Request.
El pipeline no adivina el numero: usa el que encuentre en package.json. Si nadie lo sube,
todas las prereleases seguiran colgando de la version ya publicada.
La estable es 0.16.0. Vas a añadir un componente nuevo, que es un cambio minor.
1. En tu rama, subes la version:
// projects/nebula-ui-kit/package.json
{
"name": "nebula-ui-kit",
"version": "0.17.0" // antes 0.16.0
}
2. Integras a develop. Jenkins publica sin preguntar:
nebula-ui-kit@0.17.0-dev.1 dist-tag: dev
3. Sigues trabajando. Cada integracion nueva a develop deja su propia prerelease, y
ninguna pisa a la anterior:
0.17.0-dev.2 , 0.17.0-dev.3 , ...
4. Cuando este listo, integras develop en main. Jenkins pregunta, confirmas, y sube:
nebula-ui-kit@0.17.0 dist-tag: latest
Desde ese momento, npm install nebula-ui-kit entrega la 0.17.0.
5. Para el siguiente ciclo, vuelves al paso 1 con 0.18.0, 0.17.1 o lo que corresponda.
Si publicas la 0.17.0 estable y dejas el package.json en 0.17.0, la siguiente
integracion a develop generara 0.17.0-dev.4. En SemVer una prerelease es anterior a su
version final: quedaria publicada como si fuera mas vieja que la estable que ya existe.
No rompe nada —npm la acepta, no colisiona, y quien tenga ^0.17.0 no la recibe porque las
prereleases quedan fuera de los rangos—, pero deja el historial desordenado. La forma limpia
es que el bump viaje dentro del primer Merge Request del siguiente ciclo.
En main, el pipeline lo comprueba antes de preguntar y falla con un mensaje explicito:
nebula-ui-kit@0.17.0 ya esta publicada en Nexus. Sube la version en el package.json
de la libreria antes de publicar: npm no deja repisar una version.
npm no permite repisar una version publicada. Por eso el numero se sube antes, nunca
despues.
No existe un permiso de "publicar" separado: publica quien puede integrar a la rama.
| Rama | Quien integra | Efecto |
|---|---|---|
develop |
Rol Maintainer del repositorio | Publica prerelease automaticamente |
main |
Rol Maintainer del repositorio, y ademas alguien debe confirmar en Jenkins | Publica la estable y mueve latest |
Las dos ramas estan protegidas en GitLab:
| develop | main | |
|---|---|---|
| Push directo | Maintainer | Maintainer |
| Aceptar Merge Request | Maintainer | Maintainer |
| Force push | No permitido | No permitido |
Un rol Developer puede abrir un Merge Request, pero no aceptarlo. La revision del MR es, en
la practica, el control de calidad de lo que se publica.
El usuario centrica.ci es el unico que escribe en Nexus, y solo lo hace desde Jenkins.
Nadie debe publicar a mano desde su maquina.
En orden: instalacion, lint, pruebas con cobertura, compilacion, analisis de SonarQube y
publicacion.
| Etapa | Si falla |
|---|---|
Instalacion (npm ci --legacy-peer-deps) |
Detiene el pipeline |
| Lint | Avisa y continua |
| Pruebas unitarias | Detiene el pipeline |
| Compilacion | Detiene el pipeline |
| SonarQube | Avisa y continua |
| Publicacion | Detiene el pipeline |
Por que las pruebas si bloquean aqui. En las aplicaciones el pipeline deja pasar los
fallos, porque un despliegue se rehace. Una libreria no: publica un artefacto inmutable
que consumen otros repositorios, y una version rota no se puede retirar sin romper a quien
ya la instalo.
# La estable. Es lo que debe usar cualquier proyecto salvo que haya un motivo.
npm install nebula-ui-kit
# La ultima prerelease de develop, para probar algo antes de que sea estable.
npm install nebula-ui-kit@dev
# Una version exacta, cuando necesitas reproducir un comportamiento concreto.
npm install nebula-ui-kit@0.17.0-dev.2
Instalar @dev en un proyecto que va a QA o produccion no esta permitido: una prerelease
puede cambiar en cualquier integracion a develop.
El boton de confirmar en main puede no responder. Si pulsas Publicar y no ocurre
nada, es porque la Direccion web de Jenkins (Administrar Jenkins -> System -> Jenkins
Location) no coincide con el dominio por el que entras: configurada como
http://jenkins.centricasoluciones.com:8080/ mientras se navega por
https://jenkins.centricasoluciones.com/. Para el navegador son dos sitios distintos, la
cookie de sesion no viaja en ese envio y Jenkins lo rechaza sin avisar.
Se corrige poniendo la direccion real, https://jenkins.centricasoluciones.com/, y guardando.
npm publish a mano. Publica Jenkins, siempre.main solo recibe lo que ya paso por develop y esta probado.@dev no llega a QA ni a produccion.