Comandos Essenciais da CLI do Jenkins para Gerenciamento e Controle de Jobs

A CLI do Jenkins ajuda você a gerenciar jobs quando a interface web é muito lenta para trabalhos repetitivos. Se você precisa criar jobs a partir de modelos, disparar builds ou atualizar a configuração XML em scripts, a CLI oferece um caminho direto.

Este guia foca nos comandos de gerenciamento de jobs: list-jobs, get-job, create-job, copy-job, update-job, delete-job e build.

Configurando a CLI do Jenkins

Antes de executar qualquer comando, você deve estabelecer uma conexão segura com seu mestre Jenkins. Isso envolve baixar o cliente CLI e garantir a autenticação adequada.

1. Baixando o jenkins-cli.jar

O cliente CLI geralmente é encontrado diretamente no seu servidor Jenkins em um endpoint específico. Você pode baixá-lo usando wget ou curl:

wget http://seu-url-jenkins:8080/jnlpJars/jenkins-cli.jar
# OU usando curl
curl -O http://seu-url-jenkins:8080/jnlpJars/jenkins-cli.jar

2. Métodos de Autenticação

As conexões da CLI do Jenkins exigem autenticação. O método mais seguro e recomendado é usar um Token de API em vez de uma senha de usuário simples.

Para gerar um Token de API, navegue até Configurações do Usuário > Configurar > Token de API na interface web do Jenkins.

Todos os comandos subsequentes exigirão flags de autenticação, normalmente usando as flags -s (URL do servidor) e -auth (credenciais de autenticação):

java -jar jenkins-cli.jar -s http://seu-url-jenkins:8080 -auth NOME_USUARIO:TOKEN_API <comando>

Dica: Por segurança, armazene seu token de API em uma variável de ambiente segura ou use o método de autenticação por chave SSH, se configurado, em vez de digitá-lo diretamente em scripts.

Comandos Principais para Descoberta de Jobs

Antes de modificar jobs, geralmente é necessário listar os jobs existentes e recuperar suas configurações.

Listando Todos os Jobs: list-jobs

Este comando exibe os nomes de todos os jobs configurados no mestre Jenkins.

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

Recuperando a Configuração do Job: get-job

Os jobs do Jenkins são definidos por arquivos de configuração XML. O comando get-job permite recuperar essa definição XML, essencial para criar novos jobs baseados em modelos.

# Recupere a configuração de 'meu-job-modelo' e salve em um arquivo
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job meu-job-modelo > config-modelo.xml

Comandos Essenciais de Gerenciamento de Jobs

Esses comandos lidam com as operações fundamentais do ciclo de vida dos jobs do Jenkins.

1. Criando um Novo Job: create-job

O comando create-job requer o nome do novo job e o arquivo de configuração XML que define seus parâmetros, etapas de build e gatilhos.

Pré-requisitos: Você deve primeiro ter um arquivo de configuração XML válido (ex.: nova-config.xml), geralmente derivado da modificação de um modelo recuperado usando get-job.

# Exemplo: Crie um novo job chamado 'projeto-feature-branch' usando o arquivo XML local
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job projeto-feature-branch < nova-config.xml

2. Copiando um Job Existente: copy-job

Esta é geralmente a maneira mais rápida de criar um novo job, usando um job existente como modelo e aplicando um novo nome. Este comando duplica efetivamente a configuração do job de origem.

# Sintaxe: copy-job NOME_JOB_ORIGEM NOME_JOB_DESTINO
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job pipeline-original novo-dev-pipeline

3. Habilitando e Desabilitando Jobs: enable-job e disable-job

Esses comandos são cruciais para manutenção, pausas temporárias ou controle administrativo, prevenindo ou permitindo que builds sejam disparados.

# Comando para interromper builds programados ou disparados para manutenção
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job build-projeto-legado

# Comando para reativar o job
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job build-projeto-legado

4. Excluindo um Job: delete-job

Este comando remove permanentemente um job da instância Jenkins, incluindo seu histórico de builds e configuração. Use este comando com cautela.

# Remoção permanente do job
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job job-teste-obsoleto

Aviso: O comando delete-job é executado imediatamente sem confirmação adicional no ambiente CLI. Certifique-se de que seus scripts incluam etapas de validação adequadas antes de executar este comando.

Disparando e Monitorando Builds

Além do gerenciamento de configuração, a CLI é frequentemente usada para disparar builds, especialmente aqueles que exigem parâmetros específicos.

Disparando um Build: build

O comando build inicia um novo build para o job especificado. Se o job for parametrizado, você pode passar argumentos diretamente usando a flag -p.

# Dispare um build simples, não parametrizado
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build deploy-noturno

# Dispare um job parametrizado, passando parâmetros
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build teste-integracao -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Nota: Se você usar a flag -s com build, a CLI aguardará a conclusão do build e reportará o status de saída. Caso contrário, o comando retorna imediatamente após enfileirar o build.

Visualizando o Status do Build: get-job e console

Embora a CLI não ofereça streaming em tempo real comparável à interface web, você pode verificar o status do job e recuperar a saída do console.

Para visualizar a saída do console de um número de build específico:

# Recupere a saída do console para o build #55 de 'meu-job'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console meu-job 55

Melhores Práticas para Scripts com CLI

Aproveitar a CLI do Jenkins de forma eficiente requer a adoção de práticas recomendadas específicas para estabilidade e segurança:

1. Scripts e Automação

A CLI é mais útil em scripts de shell. Use get-job, modifique o XML resultante com cuidado e então alimente a configuração modificada de volta usando create-job ou update-job.

Exemplo de Fluxo de Trabalho (Copiar, Modificar e Criar):

1. Obter modelo: get-job job-modelo > tmp.xml
2. Use sed para substituir placeholders (ex.: nome do projeto, URL do repositório) em tmp.xml.
3. Criar novo job: create-job novo-job < tmp.xml

2. Lidando com Atualizações de Configuração

Para atualizar a configuração de um job existente usando XML da entrada padrão, use update-job. Isso é mais seguro do que excluir e recriar o job, pois preserva o histórico de builds.

# Atualize 'projeto-a' usando um arquivo de configuração modificado localmente
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job projeto-a < config-atualizada.xml

3. Tratamento de Erros

Sempre verifique o código de saída ($?) após executar um comando da CLI em seus scripts. Um código de retorno 0 indica sucesso; qualquer código diferente de zero sinaliza um erro. Isso é vital para automação robusta e depuração.

Conclusão Principal

A CLI do Jenkins é uma ferramenta prática para administração repetível de jobs. Comece exportando o XML do job com get-job, faça alterações controladas, atualize jobs com update-job e dispare builds com build. Mantenha tokens de API fora dos scripts e valide comandos destrutivos como delete-job antes de executá-los.