Instalação do Jenkins e jobs: controller, agentes, credenciais e gatilhos

O Jenkins roda builds desde 2011 e não dá sinais de que vai desaparecer, principalmente porque automatiza qualquer coisa: ele não tem opinião sobre sua linguagem, seu sistema operacional ou seu destino de deploy, e seu ecossistema de plugins cobre praticamente todas as ferramentas de que um build já precisou. Essa flexibilidade também é sua fraqueza. Uma instalação padrão é um servidor de automação sem autenticação que executa comandos shell arbitrários, e uma instância Jenkins que cresceu sem planejamento por cinco anos costuma ser um amontoado de jobs configurados na mão que ninguém tem coragem de mexer.

Este guia monta o oposto disso: um controller com segurança sensata, o trabalho rodando em agentes e não no próprio servidor, credenciais no cofre de credenciais e uma configuração que você consegue reconstruir. Ele parte do princípio de que você já sabe por que quer integração contínua; o objetivo aqui é uma instalação funcional e defensável, e o vocabulário para operá-la.

As peças e como elas se encaixam

Uma instalação Jenkins tem três partes.

O controller é a aplicação web. Ele serve a interface e a API REST, armazena a configuração e o histórico de builds, agenda os builds e hospeda os plugins. Ele não deveria buildar nada sozinho.

Um agente (a documentação antiga diz "slave", e alguns campos de plugins ainda dizem) é uma máquina ou um container que roda builds. Cada agente anuncia um número de executors — slots de build concorrentes — e um conjunto de labels como linux, jdk21 ou docker. Os jobs pedem um label, e o Jenkins os agenda em um agente compatível que tenha um executor livre.

Um job — o Jenkins agora os chama de items — é uma unidade de automação: um pipeline, um projeto freestyle, um pipeline multibranch, uma pasta que os agrupa. Tudo o que um job produz durante uma execução fica em um workspace, um diretório no agente que é reaproveitado entre builds do mesmo job no mesmo agente.

O controller e os agentes conversam por uma conexão TCP que carrega um protocolo de remoting. Há dois sentidos possíveis: o controller se conecta ao agente via SSH, ou o agente se conecta ao controller em uma porta dedicada. Qual usar é uma questão de firewall, não de funcionalidade.

Instalando o controller

O Jenkins é distribuído em uma versão semanal e em uma linha LTS; as versões LTS recebem correções retroportadas por doze semanas e são as que você deve rodar em produção. A linha LTS 2.5x exige Java 17 ou 21 — o suporte ao Java 11 acabou há anos e as versões mais recentes se recusam a subir com ele.

A imagem de container é o caminho mais rápido e mantém o host limpo:

docker volume create jenkins_home

docker run -d --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  --restart unless-stopped \
  jenkins/jenkins:lts-jdk21

A porta 8080 é a interface web; a 50000 é a porta de agentes inbound, que você só precisa publicar se houver agentes se conectando ao controller. O volume nomeado é o JENKINS_HOME, e ele é o único estado que importa: se você consegue restaurar esse volume, consegue restaurar o Jenkins.

Em um host Linux, a instalação via pacote coloca o JENKINS_HOME em /var/lib/jenkins e roda sob o systemd com o usuário jenkins:

sudo apt-get install -y openjdk-21-jre fontconfig
# add the Jenkins apt repository and key as documented, then:
sudo apt-get install -y jenkins
sudo systemctl enable --now jenkins
systemctl status jenkins

Em ambos os casos, a primeira página pede uma chave de desbloqueio impressa no log e armazenada em secrets/initialAdminPassword:

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
# or, for a package install
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Aceite os plugins sugeridos, crie a primeira conta de administrador com uma senha de verdade e configure a URL do Jenkins corretamente: os plugins montam links a partir dela, e um valor errado gera webhooks e e-mails que não apontam para lugar nenhum.

Blindando a instância

Um Jenkins recém-instalado não pode ser exposto do jeito que vem. Percorra esta lista antes que qualquer outra pessoa ganhe uma conta.

1. Coloque TLS na frente

   Rode o Jenkins atrás do nginx ou de outro reverse proxy que termine o HTTPS. O Jenkins consegue servir TLS sozinho, mas um proxy traz renovação de certificados, HTTP/2 e um lugar para adicionar rate limiting. Configure o proxy para repassar os cabeçalhos originais de host e de esquema, ou o Jenkins vai avisar que a configuração do reverse proxy está quebrada.

2. Escolha um security realm

   O banco de usuários embutido serve para um punhado de pessoas. Para algo maior, conecte LDAP, Active Directory ou um provedor SAML/OIDC via plugin, para que sair da empresa remova o acesso. Nunca habilite o cadastro livre em uma instância acessível de fora.

3. Mude para autorização por matriz

   O padrão "usuários logados podem fazer qualquer coisa" é conveniente e errado. A segurança baseada em matriz, ou uma estratégia por papéis com o plugin Role Strategy, permite dar leitura a todos, build aos desenvolvedores e administração a duas pessoas. Conceda permissões a grupos, não a indivíduos.

4. Zere os executors do controller

   Manage Jenkins → Nodes → Built-In Node → defina o número de executors como 0. Assim os builds não têm onde rodar a não ser nos agentes, que é exatamente a ideia.

5. Mantenha a proteção CSRF e a script security ligadas

   As duas vêm habilitadas por padrão e as duas são desligadas de vez em quando por alguém depurando uma integração. Nenhuma deve continuar desligada. O Groovy que os pipelines executam fora do sandbox precisa ser aprovado explicitamente em In-process Script Approval.

6. Aplique patches com cronograma

   O Jenkins e seus plugins publicam avisos de segurança com frequência. Assine o feed de avisos, aplique as atualizações de plugins todo mês e os upgrades de LTS pelo menos a cada trimestre. Um Jenkins sem patches com acesso de rede à produção é um risco sério.

Adicionando agentes

O agente duradouro mais simples é um host Linux acessado via SSH. Prepare-o com um JRE e as ferramentas de build de que você precisar, crie um usuário jenkins com diretório home e adicione a chave pública do controller ao authorized_keys dele. Depois, em Manage Jenkins → Nodes → New Node, escolha um agente permanente e preencha:

• Remote root directory — um diretório de trabalho como /home/jenkins/agent, com bastante disco. É ali que ficam os workspaces.
• Labels — descritivos e específicos: linux jdk21 maven docker. Os jobs selecionam agentes por expressão de labels, então linux && docker funciona.
• Usage — "use this node as much as possible", ou "only build jobs with label expressions matching this node" para hardware especializado.
• Launch method — Launch agents via SSH, apontando para o host com a credencial SSH que você guardou no Jenkins.

Para agentes atrás de um firewall que não aceita conexões de entrada, use o método inbound no lugar. O controller fornece uma linha de comando para rodar no agente:

java -jar agent.jar \
  -url https://jenkins.example.com/ \
  -secret @/etc/jenkins/agent-secret \
  -name build-node-2 \
  -workDir /home/jenkins/agent

Rode isso sob o systemd para que ele reconecte depois de um reboot. Uma terceira opção, e a que melhor escala, são os agentes efêmeros: o plugin do Docker ou do Kubernetes sobe um container novo para cada build e o destrói ao final, de modo que nenhum estado vaza entre builds e não há agente para aplicar patch. Custa um pouco de tempo de inicialização por build e vale a pena assim que você tem mais do que um punhado de jobs.

Credenciais

Nunca coloque uma senha na configuração de um job, em um script de build ou em uma variável de ambiente digitada na interface. O Jenkins tem um cofre de credenciais, criptografado com uma chave em JENKINS_HOME/secrets, e todo plugin que precisa de um segredo lê dali.

As credenciais têm um tipo — usuário e senha, chave privada SSH, secret text (para tokens de API), secret file, certificado — e um escopo. O escopo global torna a credencial visível para todos os jobs; o escopo de sistema a restringe ao próprio Jenkins, como no caso de uma chave de conexão de agente. Guarde as credenciais em uma pasta em vez de globalmente sempre que um time for dono de um grupo de jobs: uma credencial com escopo de pasta é invisível para os jobs de fora, e essa é a forma de isolamento mais barata que o Jenkins oferece.

Cada credencial tem um ID. Dê a ela um ID estável e significativo — nexus-deploy, github-app-ci —, porque é esse ID que a configuração do job referencia:

withCredentials([usernamePassword(credentialsId: 'nexus-deploy',
                                  usernameVariable: 'NEXUS_USER',
                                  passwordVariable: 'NEXUS_PASS')]) {
    sh 'mvn -s settings.xml deploy'
}

O Jenkins mascara os valores no log do console, mas o mascaramento é uma rede de proteção, não uma garantia: um script que codifica um segredo em base64 e o imprime vai vazá-lo. Prefira credenciais com os menores privilégios possíveis e faça a rotação delas periodicamente.

Jobs freestyle e por que os pipelines os substituíram

Um projeto freestyle é configurado inteiramente por formulários web: gerenciamento de código-fonte, gatilhos de build, etapas de build e ações pós-build. Criar um é instrutivo, porque mostra a anatomia de um build.

Crie um novo Freestyle project e então:

• Source Code Management — Git, com a URL do repositório e uma credencial; especifique a branch.
• Build Steps — "Invoke top-level Maven targets" com os goals clean verify, ou "Execute shell" com os comandos que você rodaria localmente.
• Post-build Actions — publique os resultados do JUnit a partir de **/target/surefire-reports/*.xml, arquive target/*.jar e envie um e-mail em caso de falha.

Esse job funciona e leva cinco minutos para ser criado. Os limites aparecem rápido. A configuração existe apenas no XML do controller, então não é versionada com o código nem pode passar por revisão. Ela não consegue expressar uma sequência de stages com paralelismo e promoção condicional. Não sobrevive a uma reconstrução do controller, a menos que você restaure o JENKINS_HOME inteiro. E branches exigem jobs duplicados.

Um job de pipeline resolve os quatro problemas levando a definição para um Jenkinsfile commitado junto com o código-fonte. O build passa a ser revisado como código, cada branch carrega seu próprio pipeline e um controller pode ser reconstruído do zero apontando novos jobs para os repositórios. Use jobs freestyle para pequenas tarefas de manutenção; use pipelines para tudo o que builda um produto. O guia do Jenkinsfile cobre a sintaxe em profundidade.

Disparando builds

Quatro gatilhos cobrem praticamente tudo.

Webhooks são o padrão certo. O servidor Git chama https://jenkins.example.com/github-webhook/ (ou o endpoint de webhook genérico) a cada push, e o build começa em menos de um segundo, sem polling desperdiçado. Isso exige que o controller seja acessível a partir do servidor Git, o que, em uma rede privada, normalmente significa um caminho de entrada liberado em allowlist.

O polling do SCM pergunta ao repositório se algo mudou, em um agendamento como H/5 * * * *. É a alternativa quando webhooks são impossíveis. O H é uma extensão do Jenkins que significa "distribuir este job no intervalo pelo hash do seu nome", o que espalha as consultas em vez de fazer todos os jobs baterem no servidor no minuto cheio.

Builds agendados (H 2 * * *) rodam haja mudança ou não, que é o que você quer para suítes de integração noturnas, varreduras de vulnerabilidades em dependências ou testes de performance longos.

Gatilhos upstream iniciam um job quando outro termina, formando uma cadeia. Dentro de um único pipeline, os stages substituem isso; entre repositórios — uma biblioteca que dispara seus consumidores — continuam úteis.

Plugins, upgrades e configuração como código

Tudo o que o Jenkins faz, ele faz por meio de plugins — que são também seu principal risco operacional: cada um é código rodando com privilégios totais, e um plugin abandonado pelo autor vira um bloqueio no próximo upgrade de Java. Mantenha a lista curta — instale o que um job precisa, desinstale o que nada referencia e verifique atualizações em um cronograma, não quando algo quebra.

Os plugins que quase toda instalação usa: Pipeline (a suíte workflow-aggregator), Git, Credentials Binding, Matrix Authorization, JUnit, Warnings Next Generation, Docker Pipeline e Configuration as Code.

Este último merece atenção. O JCasC permite que a configuração do próprio controller fique em um arquivo YAML, de modo que a instância pode ser recriada em vez de restaurada:

jenkins:
  systemMessage: "Managed by configuration as code — do not edit through the UI"
  numExecutors: 0
  mode: EXCLUSIVE
  securityRealm:
    local:
      allowsSignup: false
  authorizationStrategy:
    globalMatrix:
      entries:
        - group:
            name: "authenticated"
            permissions: ["Overall/Read", "Job/Read"]
        - group:
            name: "developers"
            permissions: ["Job/Build", "Job/Cancel"]
unclassified:
  location:
    url: "https://jenkins.example.com/"
    adminAddress: "[email protected]"

Aponte a variável de ambiente CASC_JENKINS_CONFIG para o arquivo, mantenha-o no Git e a configuração do controller passa a ser revisável. Combine isso com uma lista de plugins com versões fixadas e reconstruir a instância vira um trabalho de quinze minutos.

Backups e disco

Tudo o que o Jenkins sabe está sob o JENKINS_HOME. Um backup que cubra os *.xml do nível superior, jobs/*/config.xml, users/, nodes/ e — fundamental — secrets/ é suficiente para reconstruir a instância. O histórico de builds e os workspaces são grandes e em grande parte descartáveis; excluir jobs/*/builds e workspace mantém o backup pequeno o bastante para rodar toda noite.

#!/usr/bin/env bash
set -euo pipefail
JENKINS_HOME=${JENKINS_HOME:-/var/lib/jenkins}
STAMP=$(date +%F)
tar -czf "/backup/jenkins-${STAMP}.tar.gz" \
    -C "$JENKINS_HOME" \
    --exclude='jobs/*/builds' \
    --exclude='workspace' \
    --exclude='caches' \
    . 

Criptografe o arquivo: ele contém o diretório secrets e, com ele, todas as credenciais que o Jenkins guarda. Depois teste uma restauração pelo menos uma vez — um backup que ninguém restaurou é uma hipótese.

O disco é o outro problema recorrente. Defina uma política de retenção de builds em cada job e limpe os workspaces nos agentes que hospedam muitos jobs; um controller que fica sem disco corrompe a configuração dos jobs na hora de gravar.

Erros comuns

• Rodar builds no controller. Isso dá a cada build acesso de leitura a todas as credenciais e derruba o servidor quando um teste consome toda a memória.
• Configurar tudo no clique. Depois de um ano, ninguém sabe dizer por que um job funciona. Leve a lógica de build para um Jenkinsfile e as configurações do controller para o JCasC.
• Segredos colados nas etapas de build. Eles acabam no XML dos jobs, nos backups e nos logs do console. Use o cofre de credenciais e withCredentials.
• Nunca fazer upgrade. Os avisos do core e dos plugins se acumulam, e pular quatro versões LTS de uma vez é muito mais difícil do que fazer uma por trimestre.
• Histórico de builds sem limite. A retenção padrão guarda tudo para sempre, e logs de console somados a artefatos arquivados vão encher o disco.
• Um único agente gigante compartilhado. Os jobs disputam portas, caches e disco. Agentes efêmeros em containers eliminam toda uma classe de mistérios do tipo "só falha no nó 3".
• Sem dono. Um Jenkins que todo mundo usa e ninguém mantém se degrada de forma previsível. Defina um responsável e dê a ele tempo para isso.

Principais pontos

• Rode a linha LTS com Java 17 ou 21, deixe o controller apenas para o agendamento e a interface, e zere o número de executors dele.
• Proteja a instância antes de abri-la: TLS via proxy, um security realm de verdade, autorização por matriz, CSRF e script security ligadas, e um cronograma de patches.
• Os agentes se conectam de saída via SSH ou de entrada pela porta de agentes; agentes efêmeros de Docker ou Kubernetes entregam builds limpos sem máquinas para manter.
• Coloque cada segredo no cofre de credenciais, restrinja o escopo a uma pasta sempre que possível e referencie-o por um ID estável.
• Jobs freestyle são uma demonstração útil de cinco minutos; pipelines definidos em um Jenkinsfile versionado são o que a automação de produção deve usar.
• Dispare com webhooks sempre que possível, recorra ao polling com hash como alternativa e use builds agendados para o trabalho noturno.
• O JENKINS_HOME é o sistema inteiro: faça backup incluindo secrets/, criptografe o arquivo, limite a retenção de builds e mantenha a configuração reproduzível com o JCasC.