Using Bamboo Specs to Define CI/CD Plans as Code

The Problem: UI Drift in Bamboo Plans

When a team edits a Bamboo plan through the web interface, those changes live only in the server’s database. If the server is rebuilt or a new engineer clones the repository, the exact build steps can be lost, leading to "works on my machine" failures.

Bamboo Specs solves this by letting you describe the plan as source code—Java or YAML—checked into Git. The Specs are compiled and published to the Bamboo server via REST, which then creates or updates the plan to match the code.

How Bamboo Specs Works

You write a class that implements BambooSpec. The define() method builds a Plan object with stages and tasks using the Specs DSL. After compiling the project into a JAR, the bamboo-specs-maven-plugin pushes the JAR to the Bamboo server. The server reconciles the received Specs with existing plans, creating new ones or updating matching plans according to the update strategy you choose.

Worked Example: Minimal Java Spec

The following Maven project defines a single‑stage plan that checks out source code and runs mvn verify.

import com.atlassian.bamboo.specs.api.BambooSpec;
import com.atlassian.bamboo.specs.api.plan.Plan;
import com.atlassian.bamboo.specs.api.plan.Stage;
import com.atlassian.bamboo.specs.api.task.CheckoutTask;
import com.atlassian.bamboo.specs.api.task.ScriptTask;

public class BuildVerifySpec extends BambooSpec {
    @Override
    public void define() {
        Plan plan = new Plan("Build and Verify", "Compile the project and run unit tests");
        Stage stage = new Stage("Build");
        stage.addTask(new CheckoutTask());
        stage.addTask(new ScriptTask("Run Maven Verify", "mvn verify"));
        plan.addStage(stage);
        this.plan(plan);
    }
}

Publishing the Specs

From the project root, run the publish goal (replace placeholders with your server URL and credentials). The user must have Admin or Specs permission.

mvn bamboo-specs:publish
  -Dbamboo.server=https://bamboo.example.com
  -Dbamboo.username=specsuser
  -Dbamboo.password=specspassword

Risk: If a plan with the same name already exists, the publish will update it to match the Specs. Any manual configuration not captured in the Specs will be reverted to the Specs definition.

Trade‑offs and Limitations

• Learning curve: Teams need to be comfortable with Java (or YAML) and the Bamboo Specs DSL, which is stricter than the GUI.
• UI gaps: Some advanced settings—such as custom repository triggers or certain deployment environment variables—are not expressible in Specs and must still be configured manually.
• Publish latency: Changes are not visible until you commit, build the JAR, and run the publish goal.

Verifying the Result

1. Log into Bamboo and confirm that a plan named "Build and Verify" appears under the expected project.
2. Open the plan configuration and verify that the Checkout task precedes the Script task.
3. Check the plan’s configuration history; Bamboo labels plans managed by Specs as "Updated via Specs".
4. If the plan is missing, inspect the Bamboo server logs for 403 or 401 errors, which usually indicate insufficient permissions for the publish user.

Rolling Back

Because the source of truth is the Specs code, you can roll back by reverting the commit that introduced the unwanted change and republishing the previous Specs version. This restores the plan to its earlier state without needing manual UI edits.

By treating your Bamboo pipelines as code, you gain version control, peer review via pull requests, and reproducible builds—eliminating the hidden drift that plagues UI‑only configurations.