Jenkins CI/CD: Crea Tu Primer Pipeline

Los pipelines de Jenkins CI/CD automatizan todo el proceso de entrega de software: desde compilar el código y ejecutar pruebas hasta desplegar aplicaciones en producción. Como el servidor de automatización open-source más utilizado del mundo, Jenkins se integra con prácticamente cualquier herramienta de desarrollo, proveedor de nube o sistema de control de versiones. Ya sea que despliegues una API en Python, una aplicación Node.js o infraestructura con Terraform, los pipelines de Jenkins definen tu proceso de entrega como código que vive junto a tu aplicación. Esta guía te lleva paso a paso desde la instalación de Jenkins hasta la escritura de tu primer pipeline y la configuración de automatización lista para producción.

Requisitos Previos

• Un servidor con al menos 2 GB de RAM y 10 GB de espacio en disco (Ubuntu 22.04 o superior recomendado)
• Java 17 o superior instalado (Jenkins requiere JDK)
• Docker instalado (opcional pero recomendado para agentes en contenedores)
• Un repositorio Git con código de aplicación para compilar
• Familiaridad básica con YAML, Groovy y scripting de shell

Instalando Jenkins

Con Docker (Recomendado)

# Crear un volumen Docker para datos persistentes
docker volume create jenkins-data

# Ejecutar Jenkins con acceso al socket de Docker (para agentes basados en Docker)
docker run -d \
  --name jenkins \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins-data:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts

# Obtener la contraseña de administrador inicial
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Con el Repositorio Oficial (Ubuntu/Debian)

# Agregar la clave y el repositorio de Jenkins
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee \
  /usr/share/keyrings/jenkins-keyring.asc > /dev/null

echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian-stable binary/" | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null

# Instalar Jenkins
sudo apt update
sudo apt install jenkins

# Jenkins arranca automáticamente — verifica el estado
sudo systemctl status jenkins

# Obtener la contraseña de administrador inicial
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Abre http://tu-servidor:8080 en el navegador, pega la contraseña inicial y sigue el asistente de configuración. Instala los plugins sugeridos — incluyen Git, Pipeline y las integraciones más habituales.

Escribiendo Tu Primer Jenkinsfile

Un Jenkinsfile define tu pipeline como código. Reside en la raíz de tu repositorio Git y Jenkins lo lee en cada ejecución.

Sintaxis de Pipeline Declarativo

// Jenkinsfile
pipeline {
    agent any

    environment {
        APP_NAME = 'my-web-app'
        DEPLOY_ENV = 'staging'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Lint') {
            steps {
                sh 'npm run lint'
            }
        }

        stage('Test') {
            steps {
                sh 'npm test'
            }
            post {
                always {
                    junit 'test-results/**/*.xml'
                }
            }
        }

        stage('Build') {
            steps {
                sh 'npm run build'
                archiveArtifacts artifacts: 'dist/**', fingerprint: true
            }
        }

        stage('Deploy to Staging') {
            when {
                branch 'main'
            }
            steps {
                sh './deploy.sh ${DEPLOY_ENV}'
            }
        }
    }

    post {
        failure {
            mail to: 'team@example.com',
                 subject: "Pipeline Failed: ${APP_NAME} #${BUILD_NUMBER}",
                 body: "Check: ${BUILD_URL}"
        }
        success {
            echo 'Pipeline completed successfully!'
        }
    }
}

Pipeline con Agentes Docker

pipeline {
    agent none    // Sin agente global — cada etapa elige el suyo

    stages {
        stage('Build') {
            agent {
                docker {
                    image 'node:18-alpine'
                    args '-v $HOME/.npm:/root/.npm'    // Cachear paquetes npm
                }
            }
            steps {
                sh 'npm ci && npm run build'
                stash includes: 'dist/**', name: 'build-output'
            }
        }

        stage('Test') {
            agent {
                docker { image 'node:18-alpine' }
            }
            steps {
                sh 'npm ci && npm test'
            }
        }

        stage('Docker Image') {
            agent any
            steps {
                unstash 'build-output'
                sh 'docker build -t myapp:${BUILD_NUMBER} .'
                sh 'docker push registry.example.com/myapp:${BUILD_NUMBER}'
            }
        }
    }
}

Cada etapa se ejecuta en un contenedor Docker limpio con la imagen especificada. Los comandos stash y unstash transfieren artefactos de build entre etapas que corren en agentes distintos.

Gestión de Credenciales y Secretos

Nunca incluyas secretos directamente en los Jenkinsfiles. Usa el Credentials Manager de Jenkins:

1. Ve a Manage Jenkins > Credentials > System > Global credentials
2. Haz clic en Add Credentials
3. Elige el tipo (Username/Password, SSH Key, Secret Text, etc.)
4. Asígnale un ID como docker-registry-creds

Usa las credenciales en tu pipeline:

stage('Deploy') {
    steps {
        withCredentials([
            usernamePassword(
                credentialsId: 'docker-registry-creds',
                usernameVariable: 'DOCKER_USER',
                passwordVariable: 'DOCKER_PASS'
            )
        ]) {
            sh 'docker login -u $DOCKER_USER -p $DOCKER_PASS registry.example.com'
            sh 'docker push registry.example.com/myapp:${BUILD_NUMBER}'
        }
    }
}

Las credenciales se inyectan como variables de entorno solo dentro del bloque withCredentials y se ocultan automáticamente en el log de build.

Comparativa de Jenkins con Alternativas CI/CD

Característica	Jenkins	GitHub Actions	GitLab CI	CircleCI
Self-hosted	Sí (principal)	Sí (runners)	Sí	No
Cloud-hosted	No (comunidad)	Sí	Sí	Sí
Configuración	Jenkinsfile (Groovy)	YAML	YAML	YAML
Ecosistema de plugins	+1800 plugins	Actions marketplace	Funciones integradas	Orbs
Soporte Docker	Via plugins	Nativo	Nativo	Nativo
Precio (self-hosted)	Gratis (open source)	Gratis (runners self-hosted)	Gratis (CE)	N/A
Curva de aprendizaje	Alta	Baja	Baja	Baja
Ideal para	Flujos enterprise complejos	Proyectos nativos de GitHub	Proyectos nativos de GitLab	Equipos SaaS-first

Usa Jenkins cuando necesites control total sobre la infraestructura de build, tengas flujos multi-rama complejos o trabajes en un entorno enterprise con requisitos de seguridad estrictos. Usa GitHub Actions para proyectos ya alojados en GitHub que necesitan CI/CD sencillo sin gestionar infraestructura propia.

Escenario Real: Pipeline Multi-Rama

Tu equipo trabaja con feature branches. Quieres que Jenkins compile y pruebe automáticamente cada rama, despliegue main a staging y solo despliegue releases etiquetadas a producción.

pipeline {
    agent { docker { image 'node:18' } }

    stages {
        stage('Build & Test') {
            steps {
                sh 'npm ci && npm test && npm run build'
            }
        }

        stage('Deploy Staging') {
            when { branch 'main' }
            steps {
                sh './deploy.sh staging'
            }
        }

        stage('Deploy Production') {
            when { tag 'v*' }
            steps {
                input message: 'Deploy to production?', ok: 'Deploy'
                sh './deploy.sh production'
            }
        }
    }
}

El paso input pausa el pipeline y espera la aprobación humana antes de desplegar a producción — una barrera de seguridad que evita releases accidentales.

Casos Especiales y Errores Comunes

Jenkins se queda sin espacio en disco: Los builds antiguos acumulan artefactos y logs. Configura la retención de builds en los ajustes del job (descartar builds antiguos) y programa una tarea cron para limpiar el workspace: jenkins-cli delete-builds job-name --range 1-100.

El pipeline se congela en el paso input: Si nadie aprueba el input, el pipeline retiene un ejecutor indefinidamente. Establece un timeout: timeout(time: 30, unit: 'MINUTES') { input ... }.

Permisos del socket Docker: Al ejecutar Jenkins en Docker con el socket montado, el usuario jenkins necesita permiso para acceder a /var/run/docker.sock. Agrega el usuario jenkins al grupo docker o ajusta los permisos del socket.

Restricciones del sandbox de Groovy: Los pipelines declarativos corren en un sandbox de Groovy que bloquea ciertas operaciones. Si necesitas Groovy sin restricciones (E/S de archivos, llamadas de red), el pipeline debe ser aprobado por un administrador en Manage Jenkins > Script Approval.

Conflictos entre versiones de plugins: Jenkins tiene más de 1800 plugins que a veces entran en conflicto. Fija las versiones de los plugins y prueba las actualizaciones en una instancia de Jenkins de staging antes de actualizar producción.

Solución de Problemas

El pipeline falla con “No such DSL method”

// Este error indica que un plugin requerido no está instalado
// Verifica que estén instalados Pipeline, Git y Docker Pipeline plugins
// Manage Jenkins > Plugins > Installed plugins

El workspace de build crece demasiado

// Añade un paso de limpieza al pipeline
post {
    always {
        cleanWs()    // Elimina el workspace tras el build
    }
}

Los webhooks no disparan el pipeline

# Verifica que Jenkins sea accesible desde tu proveedor Git
curl -I http://tu-jenkins:8080/github-webhook/

# Revisa el log del sistema de Jenkins para eventos de webhook
# Manage Jenkins > System Log > All Jenkins Logs

Resumen

• Los pipelines de Jenkins definen tu proceso CI/CD como código en un Jenkinsfile que vive en tu repositorio Git junto a la aplicación
• La sintaxis declarativa con bloques pipeline, stages y steps es el enfoque recomendado: es más fácil de leer, validar y mantener que los pipelines con scripts
• Los agentes Docker ejecutan cada etapa del pipeline en un contenedor limpio, garantizando entornos de build consistentes y eliminando el clásico “funciona en mi máquina”
• Usa el Credentials Manager para todos los secretos: nunca incluyas contraseñas, tokens o claves SSH directamente en los Jenkinsfiles
• Los pipelines multi-rama con condiciones when { branch } y when { tag } aplican automáticamente reglas de despliegue distintas según la rama
• Configura la retención de builds y la limpieza del workspace para evitar que Jenkins consuma todo el espacio en disco disponible con el tiempo

Artículos Relacionados

• Primeros pasos con GitHub Actions para CI/CD
• Docker Compose: Guía práctica para administradores de sistemas
• Terraform: Primeros pasos con infraestructura como código
• Ansible para principiantes: automatiza la configuración de servidores sin agente