Distributed Builds with Agents

Master versus Agents

The master (controller) schedules jobs and serves the UI. Agents do the actual work. Distributing work across agents keeps the controller light and lets you build on different platforms (Linux, Windows, macOS) and architectures.

Connect an SSH Agent

• On the agent: create a user, install Java + build tools.
• In Jenkins: Manage Jenkins → Nodes → New Node.
• Launch method: Launch agents via SSH with the host, user and SSH credentials.
• Optionally give it labels like linux, docker, windows.

Pin Pipelines to Labels

pipeline {
    agent { label 'linux && docker' }
    stages {
        stage('Build') { steps { sh 'make' } }
    }
}

If no matching agent is free, the build waits in the queue until one is online.

Cloud Agents

With the Docker or Kubernetes plugin, Jenkins can spin up ephemeral agents on demand - each build gets a fresh container. Nothing to patch, nothing to clean up:

agent {
    docker { image 'maven:3.9-eclipse-temurin-21' args '-v java-cache:/root/.m2' }
}

Key Points

• Labels route jobs to the right agent types.
• Ephemeral cloud agents keep builds hermetic and repeatable.
• Balance the number of executors against agent CPU/RAM.