Stop Clicking Bamboo Plans into Existence: Use Bamboo Specs as Source of Truth

Most Bamboo plans start in the web interface: a developer clicks through stages, jobs, tasks, and artifact handlers, then saves. The result works, but the definition lives only in Bamboo’s database. There is no pull request, no diff, and no easy way to reproduce the same plan on a new instance or after a restore. When someone edits a job in the UI six months later, the team rarely notices until a build fails differently.

The practical fix is to treat the plan definition like application code: store Bamboo Specs in YAML inside the same repository as the project, link that repository to the Bamboo project, and let Bamboo scan it to create or update the linked plans. After the first successful scan, the repository—not the UI—is the authoritative source.

How a Bamboo Spec scan works

A spec repository is a normal Git repository that Bamboo is told to watch. A scan is Bamboo reading the YAML files in that repository and reconciling them against the plans linked to the project. If a plan described in the spec does not exist, Bamboo creates it. If it exists, Bamboo updates it to match the file. Terms like stage, job, task, and artifact map to the same concepts you see in the Bamboo UI, just written as data.

This means a change to a build plan becomes a code review: open a branch, edit the YAML, open a pull request, and merge. Bamboo picks up the change on the next scan, or you can trigger a manual scan to verify sooner.

Worked example: a two-stage plan in YAML

Here is a minimal Bamboo Specs YAML file. It defines a plan with a Build stage that checks out the repository and publishes a test-results artifact, followed by a Test stage that consumes that artifact and runs a JUnit parser.

plan:
  project-key: PROJ
  plan-key: BUILD
  name: Application build and test
  stages:
    - stage:
        name: Build
        jobs:
          - job:
              name: Build
              tasks:
                - task:
                    source-checkout-task: {}
                - task:
                    artifact-upload-task:
                      artifact: test-results
                      copy-pattern: "target/test-results/**/*"
    - stage:
        name: Test
        jobs:
          - job:
              name: Test
              artifact-handling:
                - artifact:
                    name: test-results
                    fetch: true
              tasks:
                - task:
                    junit-parser-task:
                      spec: "target/test-results/*.xml"

Run this locally before pushing: clone the spec repository, add the file under the directory Bamboo expects for your instance, and commit.

# Run on your workstation. Replace  with your repository URL.
git clone  bamboo-specs
cd bamboo-specs
mkdir -p specs
# Add the YAML above as specs/application-build.yaml
git add specs/application-build.yaml
git commit -m "Add Bamboo Specs for application build plan"
git push origin main

Expected check: the commit appears in the repository, and after linking the repository in Bamboo and running a manual scan, a plan named “Application build and test” appears under the linked project with Build and Test stages. Risk: if the YAML references a task or artifact pattern Bamboo does not support in your version, the scan reports an error and the plan is not created or updated. Rollback: revert the spec commit and run another scan; Bamboo updates the plan to match the previous YAML.

YAML versus Java specs

Style	Best for	Trade-off
YAML	Teams that want readable, reviewable configuration	Validated only when Bamboo parses it; no compile-time checking
Java	Complex plans needing loops, conditionals, or shared libraries	Requires a build step and managing a compiled artifact

Most teams start with YAML because it lowers the review barrier. Move to Java only if a plan genuinely needs logic that YAML cannot express.

Limitations and rollout checks

Bamboo Specs do not cover every plan feature. Some triggers, permissions, and less common plugin tasks remain UI-only, and coverage depends on your Bamboo version and installed plugins. Once a plan is spec-linked, manual edits made in the Bamboo UI can be overwritten on the next scan. The team must agree that the repository wins.

Never commit credentials into a spec file. Reference Bamboo variables or linked repositories instead, so secrets stay out of version control.

Before rolling out to production plans:

1. Create a scratch project in Bamboo and link a small spec repository.
2. Run a manual scan and note which plan elements are created and which are reported as unsupported.
3. Rebuild one existing UI-built plan from a spec and diff the stages, jobs, tasks, artifacts, and triggers against the original.
4. Check your Bamboo version’s documentation for the current YAML schema and supported task list.

If the diff matches and the scan succeeds, promote one low-risk plan, require peer review for spec changes, keep the spec beside the code, and enable scheduled scans only after the manual scan is predictable.

Closing

Bamboo Specs turn build-plan configuration from a hidden click-path into a reviewed artifact. Start with one plan, verify the scan behavior in a scratch project, and let the repository become the source of truth before the next UI edit drifts out of sync.