Skip to main content
In this lesson you’ll learn how to run Jenkins jobs on specific agents using node labels. We cover both a Freestyle job (binding a job to an agent via the UI) and a Declarative Pipeline that demonstrates a global agent with a stage-level agent override. Why this matters:
  • Ensures builds run on nodes with the required OS, tools, or runtime versions.
  • Keeps resource-sensitive or platform-specific builds isolated to the correct agents.
  • Helps scale CI by distributing pipeline stages across multiple worker nodes.

​
Freestyle job

  1. From the Jenkins UI, confirm your external agent is online and ready to accept builds.
A Jenkins web UI showing the "Nodes" page with two nodes listed ("Built-In Node" and "ubuntu-agent"), their architectures, free disk/temp space and response times. The left sidebar shows build queue and executor status.
  1. Create a new Freestyle job (for example, FreestyleExternalAgent).
  2. Add a Build Step → Execute shell with the following commands to print the OS and Node.js/NPM versions available on the agent:
  1. Restrict the job to run on the external agent by enabling Restrict where this project can be run and entering the node label. In this example the label is ubuntu-docker-jdk17-node20.
A dark-themed Jenkins job configuration screen for "freestyle-external-agent," showing the General settings panel and the "Restrict where this project can be run" option with the label expression "ubuntu-docker-jdk17-node20."
  1. Save and build the job. The build console will show the job executing remotely on the matching agent and will print the OS and Node/NPM versions returned by that agent.
Example console excerpt:

​
Declarative Pipeline job

This section shows how to use a top-level (global) agent for default behavior and override it for an individual stage using a label.
  1. Create a new Pipeline job (for example, ExternalAgentsPipelineJob).
  2. Configure the job to fetch the Jenkinsfile from Git (Gitea, GitHub, etc.). In the demo the repository was imported into Gitea. Example migration parameters used for the import:
  1. Use the following Declarative Jenkinsfile. It sets agent any at the pipeline level and overrides the agent for stage S2-Ubuntu Agent to use the label ubuntu-docker-jdk17-node20:
Tip: If you need help constructing agent directives (for example, label, docker, dockerfile, none), use the Declarative Directive Generator on the Pipeline Syntax page to create the correct snippet.
A screenshot of the Jenkins web UI displaying the "Declarative Directive Generator" page with a left navigation menu and the main pane showing a form to configure an "agent" directive. The form highlights a required "Label" field and other directive options.
  1. Commit the Jenkinsfile, point the Pipeline job to your repository and branch (for example, main), and run the build.

​
Behavior and console output

  • A global agent (e.g., agent any) provides the default node for stages that do not declare their own agent.
  • A stage-level agent directive overrides the global agent for that stage only and will schedule the stage on a node that matches the provided label (or other directive).
  • If a stage is restricted to a label that no node matches, that stage remains queued until a matching agent becomes available.
Example console excerpts: Controller (stage 1 — default/global agent):
Ubuntu agent (stage 2 — label override):
You can also inspect the agent workspace (for example, /home/jenkins-agent/workspace/pipeline-external-agent) to view the checked-out repository and build artifacts. In this demo the agent workspace contains both PipelineExternalAgent and FreestyleExternalAgent folders.
Stage-level agent directives override the global agent for that stage only. If a stage is restricted to a label that no node matches, the stage will remain queued until a matching agent is available.

​
Quick reference

​
Summary

  • For Freestyle jobs, use the node label with Restrict where this project can be run to bind a job to a specific agent.
  • For Declarative Pipelines, use a global agent for default behavior and a stage-level agent to run an individual stage on a specific agent.
  • Verify which agent executed a build by checking the build console — it reports the node name and the workspace path and prints any tool versions you run during the build.
That’s all for now.

Watch Video