Bamboo Specs vs. UI-Configured Plans: A Decision Guide for Build Teams

If your team runs more than a handful of build plans in Atlassian Bamboo, the recurring pain is familiar: someone tweaks a plan in the web UI, nobody documents it, and three months later two "identical" project plans behave differently. The practical fix is to manage plans as code with Bamboo Specs. The decision is not all-or-nothing, though — this guide compares the three supported ways to define plans, explains where each fits, and shows how to validate a Specs-managed setup before committing to it.

The decision and its constraints

You are choosing how build and deployment plans are defined and changed over time. The constraints that usually matter:

• Auditability: do you need a history of who changed a plan and why?
• Scale: how many plans exist, and how often are they duplicated across projects?
• Toolchain tolerance: can the team maintain a Maven/JDK project, or does it need something lighter?
• Feature coverage: do your plans use advanced elements (complex triggers, permissions, deployment environments) that lighter-weight formats may not express?

Feature coverage in Specs varies by Bamboo version, so check the documentation matching your exact release before committing — especially if you lean toward YAML.

Comparing the three options

Option	Strengths	Weaknesses	Best fit
Java Specs	Most complete feature coverage; plans, stages, jobs, tasks, variables, permissions, deployment projects; changes go through code review	Requires JDK and Maven; steeper learning curve for non-developers	Teams with many plans, compliance needs, or complex configurations
YAML Specs	No build toolchain; easy to read and diff; lives in the repo next to the app code	Historically covers a smaller subset of plan features; complex plans can hit unsupported elements	Straightforward build plans managed by the same repo that holds the code
Web UI	Fastest to prototype; discoverable for new users; no repo setup	No versioning by default; manual reviews; copying plans invites configuration drift	One-off experiments, sandboxes, or evaluating a new plugin task

Trade-offs that bite in practice

Locked fields. Once a plan is Specs-managed, the fields controlled by the Specs source cannot be edited in the UI. This is the point — it prevents drift — but teams used to ad hoc tweaks find it surprising. Decide up front who owns the Specs repository and how urgent fixes are merged.

Drift vs. speed. UI configuration wins for a first prototype because you can click through task types and see what exists. It loses the moment a second project copies the plan by hand. A workable hybrid: prototype in the UI, then re-implement the result as Specs and treat the repository as the only source of truth from then on.

Scan misconfiguration. Bamboo picks up Specs changes by scanning a linked repository. The common failure points are repository credentials and scan permissions, not the Specs code itself. If a committed change does not appear in the plan, check the Specs scan status and repository access before debugging your Java or YAML.

Platform direction. Atlassian has ended new Server license sales and is steering customers toward Data Center. If you are making a multi-year investment in Specs, factor your licensing and upgrade path into the decision.

A concrete Java Specs example

A minimal Java Specs plan looks like this. You need a JDK and Maven installed locally, and a pom.xml with the bamboo-specs dependency matching your Bamboo version:

Plan plan = new Plan(
    new Project().key("WEB").name("Web Storefront"),
    "Build and Test", "BUILD")
  .description("CI build managed by Bamboo Specs")
  .stages(new Stage("Default Stage")
      .jobs(new Job("Unit Tests", "TEST")
          .tasks(
              new VcsCheckoutTask()
                  .description("Checkout default repository"),
              new ScriptTask()
                  .inlineBody("./mvnw -B verify"))))
  .triggers(new RemoteTrigger());

bambooServer.publish(plan);

Run the publish from your local machine or a CI job with mvn -Ppublish-specs (the exact goal depends on the archetype setup). The process needs network access to the Bamboo server and credentials with permission to create plans in the target project. Risk to note: publishing to the wrong server URL creates or overwrites plans there, so point test runs at a non-production instance first.

Validating the setup

Do not assume the Specs pipeline works because the publish command succeeded. Verify each link in the chain:

1. Publish the Specs to a test Bamboo instance and confirm the plan appears, marked as Specs-managed in the plan configuration.
2. Trigger a branch build and confirm the tasks run as defined in the Specs source.
3. Commit a small, deliberate change — add a script task or a variable — and confirm the next repository scan updates the plan with no manual UI edits.
4. Attempt to edit a Specs-controlled field in the UI and confirm it is locked. Record which fields remain editable so the team is not surprised later.
5. After several change cycles, compare the plan's effective configuration (tasks, triggers, variables) against the Specs source to confirm nothing drifted silently.

If step 3 fails, the cause is almost always repository credentials or scan permissions, not the Specs code — check Bamboo's Specs scan logs first.

Recommendation

For teams with more than a handful of plans, or any requirement to review and audit build changes, adopt Java Specs in version control and route all changes through it. Use YAML Specs for simple, repo-local build plans after confirming your Bamboo version supports every element you need. Keep the UI for prototyping only, with an explicit rule that anything surviving past the experiment gets re-implemented as Specs.