Jenkins CI/CD: Crie Seu Primeiro Pipeline

Os pipelines Jenkins CI/CD automatizam todo o processo de entrega de software — desde a compilação do código e execução de testes até o deploy de aplicações em produção. Como o servidor de automação open-source mais amplamente adotado, o Jenkins integra-se com praticamente qualquer ferramenta de desenvolvimento, provedor de nuvem e sistema de controle de versão. Seja para implantar uma API Python, uma aplicação Node.js ou infraestrutura com Terraform, os pipelines Jenkins definem seu processo de entrega como código que vive junto com a aplicação. Este guia mostra como configurar o Jenkins, escrever seu primeiro pipeline e estruturar uma automação pronta para produção.

Pré-requisitos

• Um servidor com pelo menos 2 GB de RAM e 10 GB de espaço em disco (Ubuntu 22.04 ou superior é recomendado)
• Java 17 ou superior instalado (o Jenkins requer JDK)
• Docker instalado (opcional, mas recomendado para agents containerizados)
• Um repositório Git com o código da aplicação a ser compilado
• Familiaridade básica com YAML, Groovy e shell scripting

Instalando o Jenkins

Usando Docker (Recomendado)

# Criar um volume Docker para dados persistentes
docker volume create jenkins-data

# Executar o Jenkins com acesso ao socket Docker (para agents baseados em 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

# Obter a senha de administrador inicial
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Usando o Repositório Oficial (Ubuntu/Debian)

# Adicionar a chave e a fonte do repositório 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 o Jenkins
sudo apt update
sudo apt install jenkins

# O Jenkins inicia automaticamente — verifique o status
sudo systemctl status jenkins

# Obter a senha de administrador inicial
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Abra http://seu-servidor:8080 no navegador, cole a senha inicial e siga o assistente de configuração. Instale os plugins sugeridos — eles incluem Git, Pipeline e as integrações mais comuns.

Escrevendo Seu Primeiro Jenkinsfile

Um Jenkinsfile define seu pipeline como código. Ele fica na raiz do repositório Git e o Jenkins o lê a cada build.

Sintaxe 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 com Agents Docker

pipeline {
    agent none    // Sem agent global — cada stage define o seu próprio

    stages {
        stage('Build') {
            agent {
                docker {
                    image 'node:18-alpine'
                    args '-v $HOME/.npm:/root/.npm'    // Cache dos pacotes 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 stage é executado em um contêiner Docker recém-criado com a imagem especificada. Os comandos stash e unstash transferem artefatos de build entre stages que rodam em agents diferentes.

Gerenciando Credenciais e Segredos

Nunca coloque segredos diretamente nos Jenkinsfiles. Use o Jenkins Credentials Manager:

1. Acesse Manage Jenkins > Credentials > System > Global credentials
2. Clique em Add Credentials
3. Escolha o tipo (Username/Password, SSH Key, Secret Text etc.)
4. Defina um ID como docker-registry-creds

Use as credenciais no 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}'
        }
    }
}

As credenciais são injetadas como variáveis de ambiente apenas dentro do bloco withCredentials e ficam mascaradas no log do build.

Comparando o Jenkins com Alternativas de CI/CD

Recurso	Jenkins	GitHub Actions	GitLab CI	CircleCI
Self-hosted	Sim (principal)	Sim (runners)	Sim	Não
Cloud-hosted	Não (comunidade)	Sim	Sim	Sim
Configuração	Jenkinsfile (Groovy)	YAML	YAML	YAML
Ecossistema de plugins	1800+ plugins	Actions marketplace	Recursos integrados	Orbs
Suporte a Docker	Via plugins	Nativo	Nativo	Nativo
Preço (self-hosted)	Grátis (open source)	Grátis (runners próprios)	Grátis (CE)	N/A
Curva de aprendizado	Íngreme	Baixa	Baixa	Baixa
Melhor para	Fluxos empresariais complexos	Projetos nativos do GitHub	Projetos nativos do GitLab	Times SaaS-first

Use o Jenkins quando precisar de controle total sobre a infraestrutura de build, tiver fluxos multi-branch complexos ou trabalhar em um ambiente corporativo com requisitos rígidos de segurança. Use o GitHub Actions para projetos que já estão no GitHub e precisam de CI/CD simples sem gerenciar infraestrutura.

Cenário Real: Pipeline Multi-Branch

Seu time usa feature branches. Você quer que o Jenkins compile e teste automaticamente cada branch, faça deploy do main para staging e só implante em produção com tags de versão.

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'
            }
        }
    }
}

O step input pausa o pipeline e aguarda a aprovação humana para o deploy em produção — uma barreira de segurança que previne lançamentos acidentais.

Armadilhas e Casos Extremos

Jenkins esgota o espaço em disco: Builds antigos acumulam artefatos e logs. Configure a retenção de builds nas configurações do job (discard old builds) e crie um cron job para limpar o workspace: jenkins-cli delete-builds job-name --range 1-100.

Pipeline travado no step input: Se ninguém aprovar o input, o pipeline mantém um executor de build ocupado indefinidamente. Defina um timeout: timeout(time: 30, unit: 'MINUTES') { input ... }.

Permissões do socket Docker: Ao executar o Jenkins em Docker com o socket montado, o usuário jenkins precisa de permissão para acessar /var/run/docker.sock. Adicione o usuário jenkins ao grupo docker ou ajuste as permissões do socket.

Restrições do sandbox Groovy: Pipelines declarativos rodam em um sandbox Groovy que bloqueia certas operações. Se você precisar de Groovy irrestrito (I/O de arquivos, chamadas de rede), o pipeline deve ser aprovado por um administrador em Manage Jenkins > Script Approval.

Conflitos de versão de plugins: O Jenkins tem mais de 1800 plugins e eles às vezes conflitam. Fixe as versões dos plugins e teste atualizações em uma instância Jenkins de staging antes de aplicar em produção.

Solução de Problemas

Pipeline falha com “No such DSL method”

// Esse erro indica que um plugin necessário não está instalado
// Verifique se os plugins Pipeline, Git e Docker Pipeline estão instalados
// Manage Jenkins > Plugins > Installed plugins

O workspace do build cresce demais

// Adicione uma etapa de limpeza ao pipeline
post {
    always {
        cleanWs()    // Exclui o workspace após o build
    }
}

Webhooks não estão disparando

# Verifique se o Jenkins está acessível pelo provedor Git
curl -I http://seu-jenkins:8080/github-webhook/

# Confira o log do sistema Jenkins para eventos de webhook
# Manage Jenkins > System Log > All Jenkins Logs

Resumo

• Os pipelines Jenkins definem seu processo de CI/CD como código em um Jenkinsfile que fica no repositório Git junto com a aplicação
• A sintaxe declarativa com blocos pipeline, stages e steps é a abordagem recomendada — é mais fácil de ler, validar e manter do que pipelines scripted
• Agents Docker executam cada stage do pipeline em um contêiner recém-criado, garantindo ambientes de build consistentes e eliminando o problema de “funciona na minha máquina”
• Use o Credentials Manager para todos os segredos — nunca coloque senhas, tokens ou chaves SSH diretamente nos Jenkinsfiles
• Pipelines multi-branch com condições when { branch } e when { tag } aplicam automaticamente regras de deploy diferentes por branch
• Configure retenção de builds e limpeza de workspace para evitar que o Jenkins consuma todo o espaço em disco disponível ao longo do tempo

Artigos Relacionados

• Getting Started with GitHub Actions for CI/CD
• Docker Compose: A Practical Guide for System Administrators
• Terraform: Getting Started with Infrastructure as Code
• Ansible for Beginners: Automate Server Configuration Without an Agent