Utilize Agents in Jobs

In this guide, you’ll learn how to delegate Jenkins work to external agents. We’ll first configure a Freestyle job to run on an Ubuntu agent, then build a Declarative Pipeline that switches between the controller and the same Ubuntu node.

Using an External Agent in a Freestyle Job

Ensure your external Ubuntu agent is online and labeled correctly before proceeding.

1. Inspect Available Nodes

Navigate to Manage Jenkins > Manage Nodes to view connected agents:

2. Create a New Freestyle Job

1. Click New Item, enter freestyle-external-agent, and select Freestyle project:

   

2. In the job configuration, add a Build Step → Execute shell:

   

   Insert the following commands:

   cat /etc/os-release
   node -v
   npm -v
   

3. Restrict Execution to the Ubuntu Agent

Copy the ubuntu-agent label:

Under General, check Restrict where this project can be run and paste the label:

4. Save and Build

After saving, trigger a build. The job will run on the external agent:

Console Output

Started by user siddharth
Running as SYSTEM
Building remotely on ubuntu-agent (ubuntu-docker-jdk17-node20) in workspace /home/jenkins-agent/workspace/freestyle-external-agent
+ cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
...
+ node -v
v22.11.0
+ npm -v
10.9.0
Finished: SUCCESS

Using an External Agent in a Pipeline Job

Next, we’ll build a Declarative Pipeline using both the Jenkins controller and the Ubuntu agent.

1. Clone or Migrate Your Repository

Point Jenkins to your Git repo containing Jenkinsfile:

2. Add a Declarative Jenkinsfile

Place this in your repository root:

pipeline {
    agent any

    stages {
        stage('S1 – Any Agent') {
            steps {
                sh 'cat /etc/os-release'
                sh 'node -v'
                sh 'npm -v'
            }
        }
        stage('S2 – Ubuntu Agent') {
            agent { label 'ubuntu-docker-jdk17-node20' }
            steps {
                sh 'cat /etc/os-release'
                sh 'node -v'
                sh 'npm -v'
            }
        }
    }
}

3. Configure and Run the Pipeline

1. In Jenkins, create a Pipeline job and point it to the main branch of your repo.
2. Save and click Build Now.

Console Output Highlights

[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /var/lib/jenkins/workspace/pipeline-external-agent
[Pipeline] stage (S1 – Any Agent)
+ cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
+ node -v
v20.16.0
+ npm -v
10.8.1
[Pipeline] stage (S2 – Ubuntu Agent)
Building on ubuntu-docker-jdk17-node20
+ cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
+ node -v
v22.11.0
+ npm -v
10.9.0
[Pipeline] End of Pipeline
Finished: SUCCESS

Verifying Agent Workspaces

SSH into your Ubuntu agent and list workspace directories:

ssh jenkins@ubuntu-agent
cd /home/jenkins-agent/workspace
ls
# Should list:
# freestyle-external-agent
# pipeline-external-agent

Job and Agent Summary

Links and References

• Jenkins Agents Documentation
• Declarative Pipeline Syntax
• Ubuntu Official Site
• Node.js Downloads
• npm Documentation