Choosing Between Bamboo UI Configuration and Bamboo Specs (Java or YAML)

Decision: UI-only vs Bamboo Specs

When managing Bamboo build plans you must decide whether to keep configuration solely in the Bamboo UI or to export it as code using Bamboo Specs. The decision hinges on several constraints:

• Team language preference – Java developers may favor the typed API, while YAML is accessible to broader audiences.
• Desired safety – compile‑time checking versus runtime schema validation.
• Repository strategy – whether specs live alongside application code or in a dedicated specs repo.
• Permission model – Specs imports can create or modify plans, so only trusted users/repositories should be allowed.

If you need auditability, reproducibility, and the ability to review build changes through pull requests, Specs is the preferred path. For throwaway or experimental plans, UI‑only may be acceptable.

Options comparison

Option	Tooling required	Version control	Safety / Readability	Migration effort	Typical use
UI‑only	None (browser)	No (stored in Bamboo DB)	Readable in UI, no compile safety	None to start	Quick experiments, sandbox plans
Java Specs	Java JDK, Maven/Gradle, IDE	Yes (source files)	Compile‑time safety, IDE autocomplete, verbose	Export existing plan, then maintain code	Complex plans needing conditionals, shared libraries
YAML Specs	Any text editor, YAML linter	Yes (source files)	Concise, readable; schema errors appear at import	Export existing plan, then maintain YAML	Mixed‑skill teams, simple‑to‑moderate plans

Trade‑offs

• Benefits of Specs: audit trail via Git, code review of build changes, disaster‑recovery reproducibility, ability to branch and test configuration.
• Costs: learning curve for the chosen Specs dialect, effort to migrate legacy UI plans, risk of configuration drift if team members continue editing plans in the UI after Specs adoption.
• Partial Specs: you can manage only selected aspects (e.g., stages and jobs) while leaving other settings UI‑managed, providing a stepping stone for gradual adoption. Availability and exact behavior vary by Bamboo version.

Getting started with YAML Specs (example)

This example illustrates a minimal YAML plan that creates a single stage with one script task. Adjust placeholders to match your environment.

1. Enable Specs for a repository: In Bamboo, go to Administration > Overview > Specs repositories, link the Git repository that will hold bamboo-specs/, and grant the Specs permission to the repository’s build user.
2. Add the Specs directory: At the repo root create bamboo-specs/ and place a file plan.yml with the following content:

# bamboo-specs/plan.yml
version: 2
plan:
  project-key: PROJ   # replace with your project key
  plan-key: PLAN      # replace with desired plan key
  name: Example Plan
  description: Plan created via YAML Specs
  stages:
    - name: Build
      jobs:
        - name: BuildJob
          tasks:
            - script:
                - echo "Hello from Bamboo Specs"

1. Commit and push: Add the files, commit, and push to the linked repository.
2. Trigger the Specs scan: Bamboo polls the repository (or you can manually run Repository > Scan for Specs changes). The scan logs will show whether the YAML parsed successfully and if a plan was created or updated.
3. Verify the result: In Bamboo, navigate to Projects > PROJ > PLAN. You should see the plan with the single stage and script task. Check the scan log for any schema errors; they will appear as warnings or failures.

Validation steps (run in your Bamboo instance):

• Open Administration > Overview > System to confirm your Bamboo edition and version; Specs behavior differs between Server/Data Center releases.
• After the push, view Logs > Specs scan for the repository to ensure no permission denials.
• Attempt a UI edit on the newly created plan; if Specs is active, a subsequent import will overwrite that edit, confirming the Specs‑driven mode.

Limitations and practical checks

• Specs capabilities, YAML schema keys, and permission gating are version‑sensitive. Consult the Bamboo Specs and Repository‑stored specs sections of the official documentation for your exact release before authoring files.
• Specs imports can create or overwrite plans. Always test on a sandbox project first and restrict which users/repositories may run imports via Specs security settings.
• Do not mix UI edits and Specs management on the same plan; a later import will silently overwrite manual changes.
• If you need to roll back a Specs‑driven change, revert the commit in the repository and trigger another Specs scan; the plan will be updated to the previous version.