Import a Bamboo Build Plan from Source Control Using Bamboo Specs

Problem: build-plan configuration lives only in the Bamboo UI

When a Bamboo plan is created through the web interface, its tasks, triggers, and artifacts exist in the Bamboo database, not in your source repository. A change made by one user is not automatically visible to others, and rebuilding the plan after a server failure requires remembering the exact UI settings. This makes audits, rollbacks, and reproducible environments harder than they need to be.

Useful takeaway

Store the plan definition as bamboo-specs.yaml in the repository, import it into Bamboo, and let Bamboo create or update the plan from that file. Test the change in a non-production project first, because an invalid spec can fail import or modify an existing plan.

Desired outcome

A single branch in your repository contains bamboo-specs.yaml. Bamboo imports the file, creates or updates the build plan, runs builds on commits, and publishes artifacts without requiring manual plan configuration in the Bamboo UI.

Prerequisites

• Bamboo Data Center or Cloud with Bamboo Specs enabled. Self-managed Bamboo Server is end of support; confirm your edition before relying on this procedure.
• A Git repository that Bamboo can reach, with webhook or polling configured so Bamboo detects changes. A webhook pushes a notification to Bamboo; polling has Bamboo check the repository on a schedule.
• A Bamboo user account with project administration and plan creation permissions.
• Build agents that can run the command in your spec, such as mvn test or a shell script.

Add the Bamboo Specs file to your repository

Create bamboo-specs.yaml in the repository root. The following example is representative; the exact schema depends on your Bamboo edition and version, so compare it against your instance’s Bamboo Specs documentation before applying it to production builds.

version: 2
plan:
  project: PROJ
  key: PLAN
  name: Application build
  repository:
    name: myorg/myapp
    type: git
  branches:
    - main
  stages:
    - name: Build and test
      jobs:
        - name: Run tests
          tasks:
            - script:
                inline: mvn test
          artifacts:
            - name: Surefire reports
              location: target/surefire-reports
              copyPattern: "*.xml"

Terms: project is the Bamboo project key; key is the unique plan key; stages group jobs; jobs run on agents; tasks are the steps Bamboo executes; artifacts are files preserved after the build.

Commit and push from your local terminal

1. Create a feature branch instead of pushing directly to the default branch.
2. Run:

git checkout -b add-bamboo-specs
git add bamboo-specs.yaml
git commit -m "Add Bamboo Specs build plan"
git push origin add-bamboo-specs

3. Open a pull request and have the change reviewed before merging to the branch Bamboo imports.

Where: your local development machine. Permissions: write access to the repository. Risk: pushing directly to a branch that Bamboo imports automatically can change the plan before you have reviewed it.

Import the spec into Bamboo

1. Open Bamboo and go to the project where the plan should live.
2. Select the repository import option for Bamboo Specs and point it at the repository and branch containing bamboo-specs.yaml.
3. Run the import manually, or wait for Bamboo to detect the repository change if webhooks or polling are enabled.
4. Review the import result. Bamboo should report whether the plan was created or updated.

Do not store passwords, tokens, or other secrets in plaintext in bamboo-specs.yaml. Use Bamboo variables, linked credentials, or secure agent environment variables instead.

Verify the imported plan

1. Open the plan in Bamboo and confirm its source is listed as Bamboo Specs, and that the repository and revision match the committed file.
2. Run a manual build. Check the build results for successful tasks, published artifacts, and test reports.
3. Push a test commit to the repository branch. Verify that a new build starts and that the plan updates only as intended by the spec.
4. If the plan does not appear or differs from the YAML, open the Bamboo Specs import logs for validation errors.

Recover from a failed import or bad change

This procedure changes state in Bamboo, so have a recovery path ready.

• Revert the bamboo-specs.yaml commit and re-import the spec to return the plan to its previous definition.
• Disable the plan temporarily in Bamboo while you fix the YAML.
• Inspect the Bamboo Specs import logs and the build logs for the specific validation or task failure.
• Delete and recreate the plan from a known-good spec if the imported plan is corrupted.

Limitations and version notes

• Behavior differs between Bamboo Data Center and Cloud, and across versions. Validate the exact Specs schema and permissions for your installed edition.
• Plan branches and permissions may not transfer exactly from UI-created plans to Specs. Review branch handling and role mappings after import.
• An invalid Bamboo Specs file can fail import or alter an existing plan. Test changes in a non-production project before applying to production builds.

Practical check

Open the imported plan in Bamboo, confirm the plan source is Bamboo Specs, run a manual build, and confirm that a subsequent test commit starts a new build. If all three checks pass, the spec is controlling the plan as intended.