Tools directive in Jenkins - Commands & Configuration

Introduction

When running Jenkins pipelines, you often need specific software like Java or Maven. The tools directive helps Jenkins automatically install and use these tools during your build, so you don't have to set them up manually on every machine.

When you want Jenkins to automatically install Java before running your build.

When your pipeline needs Maven to build a Java project without manual setup.

When you want to ensure consistent tool versions across different build agents.

When you want to avoid errors caused by missing or wrong tool versions on agents.

When you want to simplify pipeline scripts by declaring required tools upfront.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  tools {
    jdk 'jdk11'
    maven 'maven3'
  }
  stages {
    stage('Build') {
      steps {
        sh 'java -version'
        sh 'mvn -version'
      }
    }
  }
}

The tools block declares the tools Jenkins should install and use. Here, jdk 'jdk11' tells Jenkins to use Java 11, and maven 'maven3' tells it to use Maven 3. Jenkins will download and set these up automatically on the build agent before running the build steps.

Commands

This command updates the Jenkins job with the Jenkinsfile containing the tools directive. It ensures Jenkins knows to use the specified tools during the build.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully

This command runs inside the Jenkins build to verify that the correct Java version is installed and used as declared in the tools directive.

Terminal

java -version

Expected Output

openjdk version "11.0.18" 2023-04-18

OpenJDK Runtime Environment (build 11.0.18+10)

OpenJDK 64-Bit Server VM (build 11.0.18+10, mixed mode)

This command runs inside the Jenkins build to verify that the correct Maven version is installed and used as declared in the tools directive.

Terminal

mvn -version

Expected Output

Apache Maven 3.8.6 (cecedd343002696d0abb50b32b541b8a6ba2883f)

Maven home: /var/jenkins_home/tools/hudson.tasks.Maven_MavenInstallation/maven3

Java version: 11.0.18, vendor: Eclipse Adoptium, runtime: /usr/lib/jvm/adoptopenjdk-11-hotspot-amd64

Default locale: en_US, platform encoding: UTF-8

OS name: "Linux", version: "5.15.0-1051-azure", arch: "amd64", family: "unix"

Key Concept

If you remember nothing else from this pattern, remember: the tools directive lets Jenkins automatically install and use specific software versions needed for your build.

Common Mistakes

Not defining the tool names exactly as configured in Jenkins global tool configuration.

Jenkins cannot find or install the tool if the name does not match, causing build failures.

Use the exact tool names as set in Jenkins global tool configuration under Manage Jenkins > Global Tool Configuration.

Forgetting to configure the tools in Jenkins before using them in the tools directive.

Jenkins cannot install or use tools it does not know about, so the build will fail.

First configure the required tools in Jenkins global tool configuration with correct versions and installation methods.

Summary

The tools directive in Jenkinsfile declares software tools Jenkins should install and use during the build.

It ensures consistent tool versions and avoids manual setup on build agents.

You must configure the tools in Jenkins global tool configuration with exact names before using them.