Parametrizar Builds e Usar Scripts

Introdução

Em pipelines modernos de CI/CD (Integração Contínua/Entrega Contínua), flexibilidade e automação são fundamentais. Codificar valores fixos (hardcoding) em build jobs os torna rígidos e difíceis de gerenciar. O Jenkins permite superar isso parametrizando seus builds e executando scripts como parte do processo de build.

Neste laboratório, você aprenderá a criar um job Jenkins flexível. Você começará adicionando parâmetros para permitir a entrada do usuário no momento da construção (build time). Em seguida, aprenderá a executar scripts shell como uma etapa de build, passar os parâmetros para esses scripts e configurar ações pós-construção (post-build actions) que respondem condicionalmente ao sucesso ou falha do build. Estas são habilidades fundamentais para criar fluxos de trabalho de automação robustos e dinâmicos no Jenkins.

Uma instância do Jenkins já está em execução em seu ambiente. Você pode acessar a interface web do Jenkins abrindo o navegador Firefox na área de trabalho. O navegador abrirá automaticamente em http://localhost:8080, então você não precisa inserir o URL manualmente. Nenhum login é necessário.

Criar e Parametrizar um Projeto Freestyle

Nesta etapa, você criará um novo projeto Jenkins Freestyle e adicionará parâmetros a ele. Parâmetros tornam seus jobs interativos, permitindo que você forneça input toda vez que uma build for acionada.

Primeiro, vamos criar o job.

1. Abra o navegador Firefox na interface da área de trabalho. O navegador abrirá automaticamente em http://localhost:8080, então você não precisa digitar o URL manualmente. Nenhum login é necessário.
2. No painel principal (dashboard) do Jenkins, clique em New Item no menu à esquerda.
3. Digite parameterized-script-job como nome do item.
4. Selecione Freestyle project e clique em OK.

Você será levado para a página de configuração do job. Agora, vamos adicionar os parâmetros.

1. Na seção General, marque a caixa This project is parameterized.

   

2. Clique no dropdown Add Parameter e selecione String Parameter.

   • Name: GREETING_NAME
   • Default Value: World
   • Description: Enter a name to be greeted.

3. Clique novamente no dropdown Add Parameter e selecione Choice Parameter.

   • Name: ENVIRONMENT

   • Choices: (Digite cada opção em uma nova linha)

     DEV
     STAGING
     PROD

   • Description: Select the deployment environment.

Esses parâmetros estarão disponíveis para uso nas etapas de build posteriores.

Finalmente, role até o final e clique em Save. Você será redirecionado para a página principal do job, onde agora verá a opção Build with Parameters em vez de "Build Now".

Adicionar uma Etapa de Build com Script Shell

Nesta etapa, você adicionará um script shell ao processo de build do seu job. Esta é uma maneira comum de executar tarefas como compilar código, rodar testes ou implantar aplicações.

1. Navegue até o painel do parameterized-script-job no Jenkins.
2. Clique em Configure no menu à esquerda.
3. Role para baixo até a seção Build Steps.
4. Clique no dropdown Add build step e selecione Execute shell.
5. Na área de texto Command, insira o seguinte script. Este script criará uma estrutura de diretório de projeto dentro do workspace do Jenkins e listará seu conteúdo.

echo "--- Starting Build Step ---"
echo "Current directory:"
pwd
echo "Creating project directory structure:"
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
echo "Listing files in the project directory:"
ls -la my-app
echo "--- Build Step Finished ---"

6. Clique em Save para aplicar as alterações.

Agora, vamos executar o job para ver o script em ação.

1. Na página do job, clique em Build with Parameters.
2. Deixe os valores de parâmetro padrão e clique no botão Build.
3. Um novo build aparecerá no Build History à esquerda. Clique no número do build (ex: #1).
4. Clique em Console Output para visualizar os logs.

Você deverá ver a saída do seu script shell, incluindo a listagem de arquivos.

Started by user admin
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/parameterized-script-job
[parameterized-script-job] $ /bin/sh -xe /tmp/jenkins15539247300321029374.sh
+ echo --- Starting Build Step ---
--- Starting Build Step ---
+ echo Current directory:
Current directory:
+ pwd
/var/jenkins_home/workspace/parameterized-script-job
+ echo Creating project directory structure:
Creating project directory structure:
+ mkdir -p my-app
+ echo Version 1.0
+ echo Listing files in the project directory:
Listing files in the project directory:
+ ls -la my-app
total 12
drwxr-xr-x 2 jenkins jenkins 4096 Aug 22 01:56 .
drwxr-xr-x 3 jenkins jenkins 4096 Aug 22 01:56 ..
-rw-r--r-- 1 jenkins jenkins   12 Aug 22 01:56 version.txt
+ echo --- Build Step Finished ---
--- Build Step Finished ---
Finished: SUCCESS

Passar Parâmetros para o Script Shell

Nesta etapa, você aprenderá como usar os parâmetros que definiu na Etapa 1 dentro do seu script shell. O Jenkins expõe os parâmetros de build como variáveis de ambiente, às quais você pode acessar em seu script usando a sintaxe $NOME_DA_VARIÁVEL.

1. Volte para a página Configure (Configurar) do seu parameterized-script-job.
2. Role para baixo até a seção Build Steps (Etapas de Build) e encontre a caixa de comando Execute shell (Executar shell).
3. Substitua o script existente pelo seguinte:

echo "--- Starting Parameterized Build Step ---"
echo "Hello, $GREETING_NAME!"
echo "Deploying to the $ENVIRONMENT environment."

## Create project structure if not exists and read the version from the file
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
APP_VERSION=$(cat my-app/version.txt)
echo "Application version is: $APP_VERSION"
echo "--- Parameterized Build Step Finished ---"

Observe como $GREETING_NAME e $ENVIRONMENT são usados diretamente nos comandos echo. Quando o job for executado, o Jenkins os substituirá pelos valores selecionados pelo usuário.

4. Clique em Save (Salvar).

Agora, vamos executar o build com parâmetros personalizados.

1. Clique em Build with Parameters (Construir com Parâmetros).
2. Altere GREETING_NAME para LabEx.
3. Selecione STAGING no menu suspenso ENVIRONMENT.
4. Clique em Build (Construir).
5. Verifique a Console Output (Saída do Console) para o novo build.

A saída agora deve refletir os valores personalizados que você forneceu.

--- Starting Parameterized Build Step ---
+ echo Hello, LabEx!
Hello, LabEx!
+ echo Deploying to the STAGING environment.
Deploying to the STAGING environment.
+ mkdir -p my-app
+ echo Version 1.0
+ cat my-app/version.txt
+ APP_VERSION=Version 1.0
+ echo Application version is: Version 1.0
Application version is: Version 1.0
+ echo --- Parameterized Build Step Finished ---
--- Parameterized Build Step Finished ---

Lidar com Falhas de Build com Etapas Condicionais

Nesta etapa, você simulará uma falha de build e usará uma Ação Pós-build (Post-build Action) para executar um script de limpeza ou notificação somente quando o build falhar. Isso é crucial para criar pipelines resilientes.

Instalar o Plugin Post-build Task

Antes de podermos usar a ação de tarefa pós-build (Post-build task action), precisamos instalar o plugin necessário.

1. No Jenkins, clique no ícone de engrenagem no canto superior direito para acessar o painel de administração do Jenkins, depois clique em Plugins.
2. Clique na aba Plugins Disponíveis (Available plugins).
3. Clique em Verificar agora (Check now) para atualizar a lista de plugins.
4. Na caixa de pesquisa, procure por Post build task.
5. Marque a caixa ao lado do plugin e clique em Instalar sem reiniciar (Install without restart).
6. Aguarde a conclusão da instalação.

Modificar o Script para Simular Falha

Agora, vamos modificar o script para falhar sob uma condição específica.

1. Vá para a página Configurar (Configure) do seu parameterized-script-job.
2. Na caixa de comando Executar shell (Execute shell), substitua o script pelo seguinte:

echo "Deploying to the $ENVIRONMENT environment."

if [ "$ENVIRONMENT" = "PROD" ]; then
  echo "Error: Production deployment is not allowed!"
  exit 1
fi

echo "Deployment to $ENVIRONMENT was successful."

Este script verifica o parâmetro ENVIRONMENT. Se ele for definido como PROD, ele exibe um erro e sai com um código de saída de 1. Em scripts shell, qualquer código de saída diferente de zero sinaliza uma falha.

Agora, vamos adicionar uma ação pós-build que é acionada em caso de falha.

Adicionar Ação Pós-build

1. Role para baixo até a seção Ações Pós-build (Post-build Actions).
2. Clique em Adicionar ação pós-build (Add post-build action) e selecione Tarefa Pós-build (Post-build task).
3. No campo Texto do Log (Log text), insira Error:. Isso instrui o plugin a procurar por este texto específico no log do build.
4. No campo Script, insira o seguinte comando:

echo "FAILURE DETECTED! Sending notification..."

5. Clique em Salvar (Save).

Testar a Condição de Falha

Agora, vamos testar a condição de falha.

1. Clique em Construir com Parâmetros (Build with Parameters).
2. Selecione PROD para o ENVIRONMENT e clique em Construir (Build).
3. O build falhará, indicado por um ícone vermelho no Histórico de Builds (Build History).
4. Verifique a Saída do Console (Console Output). Você verá a mensagem de erro do seu script principal e a mensagem da sua tarefa pós-build.

Deploying to the PROD environment.
+ [ PROD = PROD ]
+ echo Error: Production deployment is not allowed!
Error: Production deployment is not allowed!
+ exit 1
Build step 'Execute shell' marked build as failure
Performing Post build task...
Match found for :Error: : True
Logical operation result is TRUE
Running script  : echo "FAILURE DETECTED! Sending notification..."
[parameterized-script-job] $ /bin/sh -xe /tmp/jenkins14011006354379294736.sh
+ echo FAILURE DETECTED! Sending notification...
FAILURE DETECTED! Sending notification...
POST BUILD TASK : SUCCESS
END OF POST BUILD TASK : 0
Finished: FAILURE

Se você executar o build novamente com DEV ou STAGING, ele será bem-sucedido, e a tarefa pós-build não será executada.

Resumo

Parabéns. Você criou com sucesso um job Jenkins flexível e robusto.

Neste laboratório, você aprendeu a:

• Criar um job Jenkins parametrizado usando parâmetros String e Choice.
• Executar scripts shell como parte de um processo de build.
• Acessar e usar parâmetros de build como variáveis de ambiente dentro de seus scripts.
• Implementar lógica condicional em um script para controlar o resultado do build.
• Configurar ações pós-build que são acionadas com base no conteúdo do log do build, permitindo que você lide com falhas de build de forma elegante.

Essas habilidades são essenciais para construir pipelines de CI/CD sofisticados que podem se adaptar a diferentes entradas e lidar com erros de forma inteligente. Agora você pode aplicar esses conceitos para automatizar seus próprios fluxos de trabalho de desenvolvimento e implantação.