Managing Bamboo Plans as Code with Bamboo Specs

The problem: CI configuration that lives only in the UI

Someone on your team clicks through the Bamboo web UI to add a stage, tweak a task, or change a trigger. Two months later nobody remembers exactly what changed, the plan on your DR instance doesn't match production, and the 'fix' is another round of clicking. Bamboo Specs is Atlassian's answer: define plans, stages, jobs, tasks, and triggers as Java code, publish them to the server, and let Git handle review and history.

The core idea is that your CI configuration lives in the same repository as the application it builds. Changes to the build plan go through pull requests, diffs, and rollbacks, just like application code.

How Bamboo Specs works

Bamboo Specs is a Java API. You scaffold a Maven project, write a PlanSpec class that declares your plan, and publish it to your Bamboo instance using a plugin. The server then creates or updates the plan and marks it as managed by specs, which restricts UI edits to the plan. The plan is now code-controlled.

The typical workflow is: scaffold a specs project, write a PlanSpec class, run the publish goal against your Bamboo instance, and the server creates or updates the plan, marking it as managed by specs so UI edits are restricted. This means you can version your CI configuration alongside your application code.

A worked example: a single-module service

Imagine a single-module service with a checkout task, a Maven test task, and an artifact definition. You write a specs plan that describes this build. Pushing the spec recreates the plan identically on a second Bamboo instance. This is useful for disaster recovery or migration. The plan is now code-controlled, and the server marks it as managed by specs.

When you need to change the plan, you edit the spec, republish, and the plan updates in place. The server creates or updates the plan, and the plan is now code-controlled. This is useful for disaster recovery or migration.

Trade-offs and limitations

The Specs API historically covered only a subset of UI capabilities. Some plugins, deployment project settings, or newer task types may still require UI configuration or REST API calls. Specs is a Java API, which suits JVM teams but is a poor fit for polyglot teams who would prefer YAML-based pipelines. That mismatch is a common reason teams choose other CI tools.

Specs-published plans can overwrite UI-made changes on republish. Establish a clear ownership rule for who edits what. Specs feature coverage and API details vary by Bamboo version; check the release notes for your installed version before relying on a specific capability.

Getting started

Create a minimal specs project with one plan and one script task, publish it to a test Bamboo instance, and confirm the plan appears and runs. Edit the spec (e.g., add an artifact), republish, and confirm the plan updates in place rather than duplicating. Compare the generated plan against the UI to identify any settings your version does not expose via Specs.

Atlassian ended new Server licenses and has been steering customers to Data Center; Bamboo's long-term product direction should be confirmed before new investment. Specs-published plans can overwrite UI-made changes on republish; establish a clear ownership rule for who edits what.