Version-Control Bamboo Build Plans with YAML Specs

The problem and the practical takeaway

Bamboo plans built entirely through the web interface exist only in the Bamboo database. A teammate can change a script task or deploy trigger without a pull request, and rolling back means hunting through plan configuration history rather than git. Bamboo Specs lets you store plan definitions as YAML files in a linked source repository. The repository becomes the single source of truth; Bamboo imports the plan from the file when you run a scan.

Desired outcome

You have a Bamboo plan whose stages, jobs, and tasks are defined in a bamboo.yaml file committed to a repository. Pushing a change to that file updates the plan in Bamboo after a scan, and the plan's Specs tab shows the linked repository, branch, and commit.

Prerequisites

• A Bamboo project where you have permission to create and edit plans.
• The YAML Specs plugin enabled on your Bamboo instance.
• A linked source repository that Bamboo can read.
• Write permission to commit to that repository.
• Repository webhooks or Bamboo repository polling enabled so Bamboo detects new commits.

Procedure: add a plan from YAML Specs

1. Author the Specs file

Create bamboo.yaml in the root of your linked repository. This example defines one plan with one stage, one job, and one script task.

version: 2
plan:
  project: PROJ
  key: APP-BUILD
  name: Application Build
stages:
  - name: Build
    jobs:
      - name: Compile and test
        tasks:
          - script:
              inline: |
                mvn clean verify

Replace PROJ with your Bamboo project key and APP-BUILD with the plan key you want. The inline value runs a command on the Bamboo agent; adjust it for your build tool and operating system.

2. Commit and push

Run these commands in a local clone of the linked repository:

git add bamboo.yaml
git commit -m "Add Bamboo YAML Specs for application build plan"
git push origin main

Where to run: your local terminal, not the Bamboo server. Permissions: write access to the repository branch. Risk: pushing directly to a protected branch may be blocked by repository branch permissions; use a feature branch and pull request if your team requires review.

3. Import the plan in Bamboo

1. Open Bamboo and go to the project where you want the plan.
2. Select Create plan or, if the plan already exists, open its Specs tab.
3. Choose the linked repository and branch containing bamboo.yaml.
4. Run Scan for Specs. Bamboo reads the YAML and creates or updates the plan.

If your Bamboo instance scans repositories automatically, the plan may appear after the next poll; otherwise the manual scan is required.

Expected checks

• The plan appears with the project key, plan key, and name from bamboo.yaml.
• The plan configuration shows the stage, job, and script task you defined.
• The plan's Specs tab lists the repository, branch, and latest commit hash that matches your push.
• A manual build runs the mvn clean verify command on an available agent and completes successfully.

Limitations and compatibility

YAML Specs do not support every task type or marketplace plugin available in Java Specs or the Bamboo UI. Before migrating a complex plan, verify that each task you need has a YAML representation in your Bamboo release. If a required task lacks Specs support, keep that plan in the UI or use Java Specs instead.

Bamboo overwrites manual UI changes when a Specs scan runs. Do not edit the imported plan's tasks through the Bamboo interface; those changes are lost on the next scan. Treat the repository file as authoritative.

Recovery and rollback

Because importing Specs creates or modifies a plan in Bamboo, you may need to revert a bad change.

1. Revert the offending commit in the repository and push the correction.
2. Run Scan for Specs again so Bamboo imports the previous definition.
3. If the scan does not fully restore behavior, open the plan's Configuration history in Bamboo, select a prior working version, and restore it. Then re-link the Specs source if necessary.

Practical verification

Push a minimal bamboo.yaml with one stage, one job, and one script task. Confirm the plan appears in Bamboo, open its Specs tab, and verify the repository, branch, and commit match your push. Then trigger a manual build and confirm the script task executes on an agent.