Architecting Bamboo Agent-Plan Mapping for Specialized Build Environments

The Problem: Build Environment Drift and Resource Contention

When scaling a CI/CD pipeline in Atlassian Bamboo, a common failure point is the "it works on Agent A but fails on Agent B" scenario. This occurs when build plans are routed to any available agent regardless of the underlying OS dependencies, SDK versions, or hardware capabilities. Without a strict mapping strategy, builds fail unpredictably, and the Bamboo server may become a bottleneck if it attempts to manage too many concurrent executions on under-provisioned hardware.

The Smallest Suitable Design

To decouple the orchestration logic from the execution load, the minimum viable architecture consists of one Bamboo Server and at least two Remote Agents. This separation ensures that a resource-heavy build (e.g., a large C++ compilation) does not freeze the Bamboo UI or crash the scheduler.

The core of this design is the Capability system. Capabilities are key-value pairs (e.g., jdk = 17 or docker = true) assigned to agents. When a Plan is configured, it requires specific capabilities; the server then filters the pool of available agents and routes the task only to those that satisfy every requirement.

Trust and Data Boundaries

Bamboo operates on a push-trigger, pull-execution model. The server pushes the build configuration and triggers the start, but the agent manages the local filesystem and process execution.

• Filesystem Boundary: Each agent maintains a local workspace. Data does not automatically sync between agents. If Plan A runs on Agent 1 and then on Agent 2, the second run starts with a fresh or cached workspace local to Agent 2.
• Permission Boundary: The Bamboo agent runs as a specific OS user. The trust boundary is defined by that user's permissions. If a build requires sudo access to restart a service, the OS user running the agent must have the corresponding NOPASSWD entries in the sudoers file.
• Network Boundary: Agents must have outbound connectivity to the server (typically via TCP) to send heartbeat signals and receive task instructions.

Configuration Example: Routing by Capability

To ensure a build requiring a specific version of Maven and a GPU-enabled environment is routed correctly, follow this configuration pattern:

Entity	Configuration / Value	Purpose
Agent Label	gpu-build-node-01	Identification
Agent Capability	maven_version = 3.8.6	Software Requirement
Agent Capability	cuda_enabled = true	Hardware Requirement
Plan Requirement	cuda_enabled = true	Routing Filter

Execution Check: To verify the mapping, run the build and check the Build Result page. The "Agent" field must explicitly list gpu-build-node-01. If the build remains in a "Pending" state, it indicates no agent currently online satisfies the cuda_enabled requirement.

Operational Checks and Failure Modes

The health of the agent-server relationship is maintained via a heartbeat signal. If the heartbeat fails, the server marks the agent as offline.

Common Failure Scenarios

• The "Pending" Build: Occurs when a plan requires a capability that no active agent possesses. Diagnostic: Compare the Plan's required capabilities against the "Capabilities" tab of all active agents.
• Zombie Processes: If an agent suffers a hard crash or resource exhaustion (OOM), the server may not immediately detect the failure, leaving the build in a "Running" state until the heartbeat timeout expires. Diagnostic: Check the agent machine's process list for orphaned build scripts.
• Workspace Corruption: Local file locks or interrupted clean-up scripts can corrupt the workspace. Resolution: Use the "Clean Working Directory" option in the plan configuration to force a fresh checkout.

Conditions for Redesigning the Architecture

The single-server, multi-agent model should be evolved when the following conditions are met:

1. High-Frequency Small Builds: If you trigger hundreds of 10-second builds per hour, the server's database and scheduler overhead will become the primary bottleneck, regardless of agent power.
2. Strict Isolation Requirements: If different plans require mutually exclusive OS versions or conflicting global environment variables, move from static remote agents to Ephemeral Agents (using Docker or Kubernetes) that are spun up and destroyed per build.
3. Cross-Region Latency: If agents are located in different geographical regions, the heartbeat latency may cause frequent false-positive disconnections. In this case, evaluate regional proxying or localizing the build clusters.

Rollback Procedure

If changing a capability requirement causes a build outage:

1. Navigate to Plan Configuration > Capabilities.
2. Remove the newly added requirement or revert the value to the previous known-working version.
3. Trigger a manual build to verify that the plan can once again be routed to the existing agent pool.