Dominando o Console de Script Groovy do Jenkins para Administração Avançada de Sistema

Jenkins é a espinha dorsal dos pipelines CI/CD modernos, oferecendo flexibilidade incomparável através de seu modelo de extensibilidade. Embora a maioria dos administradores confie na interface gráfica do usuário (GUI) ou em scripts de pipeline declarativos, o Jenkins Script Console – alimentado por Groovy – oferece uma interface direta e de baixo nível para introspecção imediata do sistema, alterações de configuração e automação avançada que vai além das etapas padrão do pipeline. Este console é indispensável para administradores de sistema que precisam solucionar problemas de produção, realizar atualizações em massa ou gerenciar o sistema central do Jenkins diretamente.

Este guia o conduzirá através do uso do Groovy Script Console para executar tarefas administrativas poderosas, transformando intervenções manuais complexas em operações eficientes e scriptáveis. O domínio desta ferramenta é fundamental para passar da gestão padrão de pipeline para a verdadeira administração do sistema Jenkins.

Compreendendo o Console de Script do Jenkins

O Console de Script do Jenkins (Gerenciar Jenkins -> Console de Script) fornece uma porta de entrada direta para interagir com o modelo de objeto do master Jenkins em execução usando Groovy, a linguagem de script preferida do Jenkins. Ele permite que os administradores acessem quase qualquer objeto dentro do tempo de execução do Jenkins, incluindo configurações de sistema, objetos de job, registros de build e agentes conectados.

Por que usar o Console de Script?

Execução Imediata: Execute scripts instantaneamente sem esperar que um job seja acionado ou que um pipeline comece.
Depuração de Sistema: Acesse o estado interno, logs e detalhes de configuração não expostos via GUI.
Operações em Massa: Modifique vários jobs, reconfigure agentes ou limpe dados antigos em toda a instância rapidamente.
Scripts de Prototipagem: Teste a lógica Groovy antes de incorporá-la em bibliotecas compartilhadas ou pipelines declarativos.

Precaução de Segurança: O Poder do Acesso Direto

AVISO: Scripts executados no console são executados com privilégios administrativos totais no master Jenkins. Um script mal escrito pode corromper configurações, excluir builds ou travar a instância do Jenkins. Sempre teste scripts complexos exaustivamente em um ambiente não produtivo primeiro.

Objetos Groovy Essenciais e Acesso à API

O poder do console vem do acesso direto aos objetos centrais do Jenkins. Esses objetos estão implicitamente disponíveis no ambiente de execução Groovy:

Jenkins.instance: O objeto singleton principal do Jenkins, representando o master em execução.
Hudson: Um alias para Jenkins.
Jenkins.instance.getItemByFullName('NomeDoJob'): Acessa um job específico.
Jenkins.instance.getComputer('NomeDoAgente'): Acessa um agente (nó) específico.

Acessando a Instância do Jenkins

Para verificar se você tem acesso, o comando mais simples é imprimir a versão do Jenkins:

println "Jenkins Version: ${Jenkins.instance.version}"
println "Running as user: ${Jenkins.instance.getAuthentication().getName()}"

Scripts Administrativos Práticos

Apresentamos a seguir vários scripts acionáveis que demonstram controle administrativo avançado via Script Console.

1. Atualizando Configurações de Job em Massa

Este script itera por todos os jobs existentes e modifica um elemento de configuração específico, como alterar uma descrição ou atualizar o URL SCM para vários projetos simultaneamente. Este exemplo adiciona um sufixo padronizado à descrição de todos os projetos Freestyle.

import hudson.model.FreeStyleProject

final String SUFFIX = " [Atualização Automatizada]"

def count = 0

Jenkins.instance.getAllItems(FreeStyleProject.class).each { job ->
    if (!job.getDescription().endsWith(SUFFIX)) {
        job.setDescription(job.getDescription() + SUFFIX)
        job.save()
        println "Updated description for: ${job.getName()}"
        count++
    }
}
println "\nFinished. Total jobs updated: ${count}"

2. Gerenciando Agentes (Nós) do Jenkins

Administradores frequentemente precisam colocar agentes offline para manutenção ou desconectar manualmente nós com mau funcionamento.

Desconectando um Agente Temporariamente

Este script desconecta um agente, impedindo que novas builds iniciem nele, mas permitindo que builds em execução terminem.

import hudson.model.Computer

final String AGENT_NAME = "meu-agente-especifico"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Set temporarily offline
    agent.setTemporarilyOffline(true, "Manutenção iniciada por Script Admin.")
    println "Agent '${AGENT_NAME}' set to temporarily offline."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

Forçando um Agente Offline e Desconectando Tarefas em Execução

Se um agente precisar ser derrubado imediatamente, você pode forçá-lo offline e desconectar quaisquer builds em execução, o que as marcará como falhas ou abortadas, dependendo da configuração.

import hudson.model.Computer

final String AGENT_NAME = "nodo-nao-responde-01"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Force offline and disconnect running tasks immediately
    agent.doDoDisconnect()
    println "Agent '${AGENT_NAME}' forcefully disconnected."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

3. Manipulando Builds em Execução

Quando uma build crítica fica travada ou precisa de cancelamento imediato, o Script Console oferece o caminho mais rápido.

Abortando uma Build Específica em Execução

Para abortar uma build identificada por seu caminho completo (por exemplo, JobDoPipeline/NumeroDaBuild):

// Example: Aborting build #5 of the job named 'CriticalDeploy'
final String JOB_NAME = "DeployCritico"
final int BUILD_NUMBER = 5

def job = Jenkins.instance.getItemByFullName(JOB_NAME)

def build = job.getBuild(BUILD_NUMBER)

if (build && build.isBuilding()) {
    build.doCancel()
    println "Build ${JOB_NAME}#${BUILD_NUMBER} has been cancelled."
} else {
    println "Build ${JOB_NAME}#${BUILD_NUMBER} is not running or does not exist."
}

4. Limpando Registros de Builds Antigas

Gerenciar espaço em disco frequentemente exige a poda agressiva de builds antigas. Este script identifica e exclui todas as builds com mais de 30 dias para um job especificado.

import hudson.model.Job
import java.util.concurrent.TimeUnit

final String TARGET_JOB = "JobDeArquivamentoLegado"
final int DAYS_TO_KEEP = 30

def job = Jenkins.instance.getItemByFullName(TARGET_JOB)

if (job instanceof Job) {
    long cutoffTime = System.currentTimeMillis() - TimeUnit.DAYS.toMillis(DAYS_TO_KEEP)
    int deletedCount = 0

    job.getBuilds().each { build ->
        if (build.getTimeInMillis() < cutoffTime) {
            println "Deleting old build: ${build.getDisplayName()}"
            build.delete()
            deletedCount++
        }
    }
    println "\nCleanup complete. Deleted ${deletedCount} builds for ${TARGET_JOB}."
} else {
    println "Job '${TARGET_JOB}' not found or is not a standard Job type."
}

Melhores Práticas para Scripting no Console

Ao realizar alterações em nível de sistema, adira a estas melhores práticas para manter a estabilidade:

Use .save(): Sempre que você modificar um objeto de configuração (como um Job ou View), você deve chamar .save() nesse objeto para que a alteração persista após o Jenkins reiniciar. As configurações são mantidas apenas na memória até serem salvas.
Verifique a Existência do Objeto: Sempre envolva chamadas de API com verificações (if (objeto) ou try-catch) para evitar que o console trave se você digitar incorretamente um nome de job ou agente.
Evite Loops Persistentes: Os scripts são executados de forma síncrona. Não execute loops ou processos de longa duração diretamente no console, a menos que tenha certeza de que eles serão concluídos rapidamente, pois isso bloqueará a UI do console.
Aproveite Métodos Integrados: Objetos Groovy do Jenkins frequentemente têm métodos auxiliares específicos (como doCancel() ou doDoDisconnect()). Use-os em vez de tentar manipular manualmente o estado interno sempre que possível.
Use o Modo Silencioso (se aplicável): Ao realizar operações em massa que geram atualizações excessivas de status de build, considere se desabilitar temporariamente os recursos de notificação de eventos é justificado, embora isso geralmente exija acesso mais profundo ao sistema do que a administração padrão.

Dominar o Jenkins Groovy Script Console o transiciona de meramente usar o Jenkins para administrá-lo e otimizar seu núcleo ativamente. Ao praticar essas técnicas, você obtém controle granular sobre seu servidor de automação, melhorando drasticamente a capacidade de resposta durante janelas de manutenção complexas ou emergências.