Choosing Bamboo Deployment Projects for Atomic Multi‑Stage Releases

Problem & Takeaway

When a team needs a single, version‑controlled pipeline that builds, tests, and deploys to several environments atomically, Bamboo’s Deployment Projects are a natural fit. The core decision is how to structure the environments, where to place approvals, and how to isolate agents. The goal of this article is to present the supported options, compare them in a concise table, explain the trade‑offs, and give a concrete Java‑DSL example that can be committed to a repository and imported into Bamboo.

Decision Context

Typical constraints that influence the choice of Deployment Project configuration:

• Multiple target environments (dev, qa, prod).
  Each environment may have different deployment steps or target hosts.
• Build artifacts produced by a preceding build plan must be consumed by the deployment project.
• Resource isolation: each environment should run on an agent queue that has the correct permissions and resources.
• Governance: a manual approval gate is required before any production deployment.
• Version control: the deployment project definition should live alongside build plans and be subject to code‑review.

Supported Options

Bamboo Deployment Projects expose the following key configuration knobs:

Option	Configuration	Key Feature	Typical Use
Sequential Environments	Environments are defined in a fixed order; later environments start only after the previous one succeeds.	Guarantees order, simple artifact flow.	Linear pipelines where each environment depends on the previous one.
Parallel Environments	Multiple environments run concurrently after a shared artifact is available.	Reduces total pipeline time.	When environments are independent or you want to save time.
Manual Approval Task	Insert a Manual Approval task in an environment.	Human oversight before critical steps.	Production deployments that need a final sign‑off.
Automatic Approval Task	Use a Script task that always passes or a Wait task with a timeout.	Fast‑track for non‑critical environments.	Staging or testing releases where no manual review is needed.
Agent Queue Assignment per Environment	Specify an agent queue for each environment.	Isolates resources and permissions.	When certain stages need privileged agents or specific host access.
Concurrency Limits	Set Maximum concurrent deployments for the project or per environment.	Prevents over‑subscription of agents.	Large teams sharing a pool of agents.

Trade‑Off Analysis

• Speed vs. Safety: Parallel environments finish faster but increase the risk of race conditions on shared resources. Sequential environments are safer but slower.
• Human Oversight vs. Automation: Manual approvals add accountability but delay releases. Automatic approvals speed up the pipeline but risk bypassing checks.
• Resource Isolation vs. Complexity: Assigning different agent queues per environment keeps permissions tight but requires more queue configuration and can lead to idle time if queues are mis‑configured.
• Concurrency Limits vs. Utilization: Tight limits protect agents but can throttle throughput. Loose limits maximize speed but risk agent starvation.

Concrete Java‑DSL Implementation

Below is a minimal Bamboo Specs Java example that demonstrates a Deployment Project with two environments: Test and Deploy to Prod. The example uses a manual approval gate before production and assigns distinct agent queues to each environment. The code is intended for Bamboo 7.x and later; earlier versions require a slightly different DSL but the concepts remain the same.

package com.example.bamboo;

import com.atlassian.bamboo.specs.api.BambooSpecsProject;
import com.atlassian.bamboo.specs.api.builders.DeploymentProject;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectEnvironment;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTask;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskScript;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskManualApproval;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskArtifactDownload;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskArtifactDownload.ArtifactDownloadSource;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskArtifactDownload.ArtifactDownloadSource.Build;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskArtifactDownload.ArtifactDownloadSource.BuildPlan;
import com.atlassian.bamboo.specs.api.builders.DeploymentProjectTaskArtifactDownload.ArtifactDownloadSource.BuildPlan.BuildPlanKey;

@BambooSpecsProject
public class DeploymentProjectSpec {
    public DeploymentProject deploymentProject() {
        DeploymentProject project = new DeploymentProject("DEPLOY", "App Deployment")
            .description("Automated multi‑stage release with manual gate before prod.")
            .environment(testEnvironment())
            .environment(deployProdEnvironment());
        return project;
    }

    private DeploymentProjectEnvironment testEnvironment() {
        return new DeploymentProjectEnvironment("Test")
            .agentQueue("build-queue")
            .task(new DeploymentProjectTaskArtifactDownload()
                .source(new ArtifactDownloadSource(new BuildPlan("Build-App")))
                .artifactName("app.jar"))
            .task(new DeploymentProjectTaskScript()
                .description("Run unit tests")
                .interpreter("bash")
                .script("java -jar app.jar --test"));
    }

    private DeploymentProjectEnvironment deployProdEnvironment() {
        return new DeploymentProjectEnvironment("Deploy to Prod")
            .agentQueue("deploy-queue")
            .task(new DeploymentProjectTaskManualApproval()
                .description("Approve deployment to production"))
            .task(new DeploymentProjectTaskArtifactDownload()
                .source(new ArtifactDownloadSource(new BuildPlan("Build-App")))
                .artifactName("app.jar"))
            .task(new DeploymentProjectTaskScript()
                .description("Deploy to production")
                .interpreter("bash")
                .script("scp app.jar user@prod:/opt/app/\nssh user@prod 'systemctl restart app'"));
    }
}

Where to run: Place the Java source file in a Maven project that is part of your repository. Commit the file, build the project, and push the resulting JAR to Bamboo’s Specs repository. Bamboo will automatically detect the new spec and create the Deployment Project.

Permissions: The agent queue build-queue must have read access to the artifact repository where app.jar is stored. The deploy-queue must have SSH keys configured for the production host.

Validation Checklist

1. Run the build plan Build-App and confirm that app.jar is uploaded to Bamboo’s artifact repository.
2. Navigate to the Deployment Project in the Bamboo UI and trigger a deployment.
3. In the Test environment logs, look for the artifact download step and the unit test command.
4. When the Deploy to Prod environment reaches the manual approval task, the UI should pause and display a “Waiting for approval” status.
5. Approve the gate from the UI and verify that the deployment script runs, producing a systemctl restart app entry on the production host.
6. To test concurrency limits, configure the project to allow only one concurrent deployment and start two deployments simultaneously. The second should queue until the first completes.

Limitations and Caveats

• Java‑DSL syntax may differ between Bamboo 7.x and 8.x. Refer to the official Bamboo Specs documentation for the exact API version.
• Manual approval tasks rely on Bamboo’s built‑in permission model; they do not integrate with Jira Service Management automatically. If you need JSM tickets, you must create a separate JSM workflow that triggers the deployment via the REST API.
• Artifact download tasks require the exact artifact name and build plan key. A mismatch will cause the task to fail.
• Agent queue names must match queues configured in Bamboo; otherwise the environment will be queued indefinitely.

Practical Check

After editing the spec, run mvn clean package to build the JAR and then curl -X POST -u admin:password -H "Content-Type: application/json" -d @deployment-project.json https://bamboo.example.com/rest/api/latest/specs to push the spec. The REST API will return a 200 status if the spec is valid. If you encounter a 400 Bad Request, review the error message for missing or invalid fields.

Conclusion

For teams that require atomic, multi‑environment releases with a production approval gate, a Bamboo Deployment Project configured with sequential environments, a manual approval task, and agent queue isolation provides the most robust solution. Parallel environments and automatic approvals can be added later once the pipeline’s stability has been verified. By keeping the spec in source control and validating it with the REST API, you maintain a repeatable, auditable deployment process that aligns with modern CI/CD best practices.