pll-jenkins

CLI interativo para gerenciar jobs Jenkins via terminal. Permite baixar (pull) e subir (push) jobs de uma pasta Jenkins diretamente para um repositório git, usando a branch atual como referência automática.

Dependências do sistema

Antes de instalar, certifique-se de ter os seguintes programas disponíveis no PATH:

| Dependência | Motivo | Instalação (Ubuntu/Debian) | |---|---|---| | Java (JRE) | Executa o jenkins-cli.jar | sudo apt install default-jre | | jq | Processa respostas JSON da API Jenkins | sudo apt install jq | | curl | Faz chamadas HTTP nos scripts shell | sudo apt install curl |

O jenkins-cli.jar já vem embutido no pacote — não é necessário baixar separadamente.

Instalação

npm install -g @grupopll/pll-jenkins

Após a instalação, o comando pll-jenkins estará disponível globalmente.

Configuração de credenciais

Na primeira execução de qualquer comando, o CLI irá pedir a URL, usuário e token do Jenkins e salvará automaticamente em ~/.pll-jenkins.json (com permissão restrita 600).

? URL do Jenkins (ex: https://jenkins.exemplo.com): https://seu-jenkins.com
? Usuário Jenkins: seu-usuario
? Token Jenkins: ********

Nas próximas execuções as credenciais são carregadas automaticamente, sem perguntar nada.

O token pode ser gerado em: https://seu-jenkins.com/user/<seu-usuario>/configure → API Token

Uso

pll-jenkins <comando>

Comandos:
  list    Lista jobs e pastas no Jenkins
  pull    Baixa jobs do Jenkins para o repositório local
  push    Sobe jobs locais de volta para o Jenkins

pll-jenkins list

Lista a árvore de jobs e pastas a partir de uma pasta do Jenkins.

pll-jenkins list

? Pasta inicial (deixe vazio para raiz):

/
├── Meu-Projeto/
│   ├── main/
│   │   ├── [JOB] Auth-Request
│   │   └── [JOB] Pipeline-Deploy
│   └── uat/
│       └── [JOB] Auth-Request
└── Outro-Projeto/
    └── [JOB] Build

pll-jenkins pull

Baixa os jobs de uma pasta Jenkins para dentro do repositório git local, na pasta jenkins/.

cd meu-repo-git   # branch: main
pll-jenkins pull

Primeira execução: abre um seletor interativo para escolher o projeto raiz no Jenkins (ex: Meu-Projeto). A branch git atual é adicionada automaticamente ao caminho (Meu-Projeto/main).

? Selecionar projeto Jenkins:
  > Meu-Projeto/  (entrar)
    [Usar esta pasta]
    Outro-Projeto/  (entrar)

Após a seleção, o arquivo jenkins/.pll-jenkins é criado com o nome do projeto e os jobs são baixados:

meu-repo-git/
└── jenkins/
    ├── .pll-jenkins          ← salvo automaticamente
    ├── Auth-Request/
    │   └── config.xml
    └── Pipeline-Deploy/
        └── config.xml

Execuções seguintes: o projeto é lido automaticamente do jenkins/.pll-jenkins. Basta trocar de branch e rodar novamente:

git checkout uat
pll-jenkins pull   # baixa Meu-Projeto/uat automaticamente

pll-jenkins push

Sobe os jobs da pasta jenkins/ local de volta para o Jenkins, usando a branch atual para determinar o destino.

cd meu-repo-git   # branch: main
pll-jenkins push

Projeto      : Meu-Projeto  (lido de jenkins/.pll-jenkins)
Branch atual : main
Pasta Jenkins: Meu-Projeto/main
Origem local : /home/user/meu-repo-git/jenkins

? Push de "/home/user/meu-repo-git/jenkins" → Jenkins "Meu-Projeto/main". Confirmar? (Y/n)

Se a pasta Meu-Projeto/<branch> não existir no Jenkins, o CLI pergunta se deseja criá-la antes de fazer o push:

A pasta "Meu-Projeto/uat" não existe no Jenkins.
? Criar pasta "Meu-Projeto/uat" no Jenkins? (Y/n)
Criando pasta "Meu-Projeto/uat"...
Pasta criada com sucesso.

Fluxo típico por projeto

# 1. Clone o repositório
git clone [email protected]:sua-empresa/meu-projeto.git
cd meu-projeto

# 2. Baixe os jobs da branch main
pll-jenkins pull

# 3. Edite os config.xml conforme necessário
vim jenkins/Auth-Request/config.xml

# 4. Suba de volta para o Jenkins
pll-jenkins push

# 5. Trabalhe em outra branch
git checkout -b uat
pll-jenkins pull    # baixa Meu-Projeto/uat
pll-jenkins push    # sobe para Meu-Projeto/uat (cria se não existir)

Estrutura do repositório após o pull

meu-repo-git/
└── jenkins/
    ├── .pll-jenkins          ← não commitar (adicione ao .gitignore) ou commitar para fixar o projeto
    ├── NomeDoJob/
    │   └── config.xml
    └── OutroJob/
        └── config.xml

Dica: adicione jenkins/.pll-jenkins ao .gitignore se diferentes desenvolvedores usarem projetos Jenkins distintos, ou commite o arquivo para fixar o projeto para todo o time.

Credenciais salvas

| Arquivo | Conteúdo | |---|---| | ~/.pll-jenkins.json | { "url": "...", "user": "...", "token": "..." } |

Para redefinir as credenciais, apague o arquivo:

rm ~/.pll-jenkins.json

Solução de problemas

| Erro | Causa | Solução | |---|---|---| | Credenciais inválidas (401) | Token expirado ou incorreto | Gere um novo token no Jenkins e apague ~/.pll-jenkins.json | | Pasta não encontrada (404) | Pasta não existe no Jenkins | Verifique o nome ou use pll-jenkins list | | java: command not found | Java não instalado | sudo apt install default-jre | | jq: command not found | jq não instalado | sudo apt install jq | | jenkins/.pll-jenkins não encontrado | Pull ainda não foi feito | Execute pll-jenkins pull primeiro | | Não está em um repositório git | Pasta sem git | Execute dentro de um repositório git |