Build wrappers in Jenkins - Commands & Configuration

Introduction

Build wrappers in Jenkins prepare the environment before the actual build starts. They help set up things like environment variables, credentials, or special tools needed for the build to run smoothly.

When you need to inject environment variables for your build steps.

When you want to clean up or prepare the workspace before building.

When you need to run a script or tool setup before the main build starts.

When you want to wrap your build with special logging or timeout controls.

When you need to manage credentials securely during the build process.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  options {
    buildDiscarder(logRotator(numToKeepStr: '5'))
  }
  environment {
    EXAMPLE_VAR = 'HelloWorld'
  }
  stages {
    stage('Prepare') {
      steps {
        echo "Using build wrapper to set environment variable: ${EXAMPLE_VAR}"
      }
    }
    stage('Build') {
      steps {
        sh 'echo Building the project...'
      }
    }
  }
  // Note: Jenkins pipeline does not have a direct wrappers block,
  // but wrappers are configured via plugins or options like 'timeout' or 'timestamps'
}

This Jenkinsfile shows how environment variables can be set in the environment block, which acts like a build wrapper by preparing the environment before build steps run.

Build wrappers in Jenkins classic UI are often configured via plugins, but in pipelines, similar effects are achieved with options and environment blocks.

Commands

This command triggers the Jenkins pipeline named 'example-pipeline' to start the build process.

Terminal

jenkins-cli build example-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Using build wrapper to set environment variable: HelloWorld

[Pipeline] sh

+ echo Building the project...

Building the project...

[Pipeline] End of Pipeline

Finished: SUCCESS

This command retrieves the configuration of the 'example-pipeline' job to verify its settings including environment variables and wrappers.

Terminal

jenkins-cli get-job example-pipeline

Expected Output

<?xml version="1.0" encoding="UTF-8"?>

<flow-definition plugin="workflow-job@2.44">

  <description></description>

  <definition class="org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition" plugin="workflow-cps@2.93">

    <script>pipeline { agent any; environment { EXAMPLE_VAR = 'HelloWorld' } stages { stage('Prepare') { steps { echo "Using build wrapper to set environment variable: ${EXAMPLE_VAR}" } } stage('Build') { steps { sh 'echo Building the project...' } } } }</script>

    <sandbox>true</sandbox>

  </definition>

  <triggers/>

</flow-definition>

Key Concept

If you remember nothing else from build wrappers, remember: they prepare the environment so your build steps run with the right settings and tools.

Common Mistakes

Trying to use a 'wrappers' block directly inside a Jenkins pipeline script.

The declarative pipeline syntax does not support a 'wrappers' block; wrappers are handled differently via environment, options, or plugins.

Use the 'environment' block for variables and 'options' for build controls, or configure wrappers via Jenkins UI plugins for freestyle jobs.

Not setting environment variables in the correct scope, causing build steps to not see them.

Environment variables must be set in the pipeline's 'environment' block or inside steps to be available during build.

Define environment variables in the 'environment' block at the pipeline or stage level.

Summary

Build wrappers prepare the environment before build steps run in Jenkins.

In pipelines, use the 'environment' block to set variables and 'options' for build controls.

Use Jenkins CLI commands to trigger builds and check job configurations.