Tools directive in Jenkins - Step-by-Step Execution

Process Flow - Tools directive

Start Pipeline

↓

Tools Directive Declared

↓

Jenkins Installs/Uses Tool

↓

Tool Available in PATH

↓

Pipeline Steps Use Tool

↓

Pipeline Completes

The Tools directive tells Jenkins which tool version to use, Jenkins sets it up, then the pipeline uses that tool.

Execution Sample

Jenkins

pipeline {
  agent any
  tools {
    maven 'Maven 3.8.1'
  }
  stages {
    stage('Build') {
      steps {
        sh 'mvn -version'
      }
    }
  }
}

This Jenkins pipeline uses the Tools directive to specify Maven version 3.8.1, then runs 'mvn -version' to show the tool is available.

Process Table

Step	Action	Tool Directive Effect	Pipeline State	Output
1	Start pipeline	No tool set yet	Pipeline initializing	No output
2	Read tools directive	Maven 3.8.1 requested	Preparing tool environment	No output
3	Jenkins sets up Maven 3.8.1	Maven installed and added to PATH	Tool environment ready	No output
4	Run 'mvn -version' command	Uses Maven 3.8.1 from PATH	Build stage running	Apache Maven 3.8.1 ...
5	Pipeline completes	Tool usage done	Pipeline finished	Build success

💡 Pipeline ends after build stage completes successfully with specified tool

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Maven Version	None	3.8.1 requested	3.8.1 installed	3.8.1 used	3.8.1 used

Key Moments - 3 Insights

Why does Jenkins install the tool even if it is already on the system?

Jenkins installs the tool version specified in the tools directive to ensure consistent environment regardless of system setup, as shown in step 3 of the execution table.

What happens if the tool version specified is not configured in Jenkins?

The pipeline will fail to start the tool because Jenkins cannot find or install the requested version, stopping before step 4 where the tool is used.

Does the tools directive run the tool commands automatically?

No, the tools directive only sets up the tool environment. The pipeline steps must explicitly run commands like 'mvn -version' as in step 4.

Visual Quiz - 3 Questions

Look at the execution table, at which step does Jenkins add the tool to the PATH?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Check the 'Tool Directive Effect' column for when Maven is installed and added to PATH.

According to the variable tracker, what is the Maven version after step 4?

A 3.8.1 used

B 3.8.1 requested

C 3.8.1 installed

D None

💡 Hint

Look at the 'After Step 4' column for 'Maven Version' in the variable tracker.

If the tools directive was removed, what would likely happen at step 4?

A 'mvn -version' runs with default system Maven

B 'mvn -version' fails because Maven is not set up by Jenkins

C Pipeline skips the build stage

D Pipeline installs Maven automatically anyway

💡 Hint

Refer to the explanation in key moments about tool setup and usage.

Concept Snapshot

Tools directive in Jenkins pipeline:
- Declared inside 'tools' block
- Specifies tool name and version (e.g., maven '3.8.1')
- Jenkins installs and adds tool to PATH
- Pipeline steps use the tool commands
- Ensures consistent tool environment across builds

Full Transcript

The Tools directive in Jenkins pipelines tells Jenkins which tool and version to use. When the pipeline starts, Jenkins reads this directive and installs the specified tool version if needed. It then adds the tool to the PATH so pipeline steps can run commands using that tool. For example, specifying Maven 3.8.1 ensures that when the pipeline runs 'mvn -version', it uses that exact Maven version. This setup guarantees consistent builds regardless of the system's default tools. The pipeline completes after running the build steps with the configured tool.