Bamboo Specs Groovy DSL vs UI-driven plan configuration for parameterized multi-stage pipelines

Direct Answer

For parameterized multi-stage pipelines, Groovy DSL in Bamboo Specs takes precedence over UI-defined variables when the Spec is applied, but the synchronization behavior depends on whether you use repository-stored Specs (Bamboo Specs) or local Specs. Repository-stored Specs automatically sync on commit; local Specs require manual application. Stage-specific artifact paths can be parameterized in Groovy, but doing so removes those fields from UI visual editing — they become read-only in the interface.

Parameter Precedence: Groovy vs UI Variables

When a Bamboo Spec (Groovy DSL) is applied to a plan, it becomes the source of truth for the plan structure and default variable values. The precedence rules are:

• Spec-defined variables set the baseline defaults and structure. These are written into the plan configuration when the Spec is processed.
• UI-defined plan variables act as runtime overrides. They persist in the plan configuration but are not overwritten by subsequent Spec applications unless the Spec explicitly redefines them.
• Branch-specific or deployment variables override both at execution time.

If a variable exists in both the Spec and the UI, the Spec's value is used as the default for new branches and plan copies, but the UI value remains as an explicit override on the current plan. This means non-technical stakeholders can still adjust values in the UI without breaking the Spec, but those adjustments won't propagate to other plans or branches derived from the Spec.

Automatic Synchronization on Spec Commit

Repository-stored Specs (Bamboo Specs) synchronize automatically when changes are pushed to the linked repository. Bamboo polls the repository (default: 1 minute) or receives webhooks, then reapplies the Spec to the plan. Plan variable values defined in the Groovy DSL are updated to match the new defaults.

Local Specs (run via Maven or CLI) do not auto-sync. They require manual re-execution to push changes to the server.

Critical nuance: when a repository-stored Spec reapplies, it recreates the plan structure (stages, jobs, tasks) but preserves UI-set variable overrides unless the Spec explicitly declares those variables with new values. If you want the Spec to force-update a variable, you must include it in the DSL with the new default.

Parameterizing Artifact Paths Without Losing UI Editing

You can parameterize artifact paths in Groovy DSL:

stage('Build') {
    job('Compile') {
        tasks {
            maven('mvn package')
        }
        artifacts {
            artifact('target/*.jar') {
                location = "${project.version}/artifacts"
                pattern = "**/*.jar"
            }
        }
    }
}

However, once applied:

• The artifact definition appears in the UI but is read-only — the pencil icon is disabled.
• Non-technical users cannot modify paths, patterns, or copy behavior through the visual editor.
• To regain UI editability, you must remove the artifact definition from the Spec and manage it entirely in the UI (losing version control).

Workaround: define artifact patterns in the Spec but leave copy locations as UI-configurable by omitting the location field in the DSL. This is not officially documented and may change.

Verification Steps for Your Environment

1. Create a test plan via UI, add a plan variable DEPLOY_ENV=staging.
2. Write a minimal Groovy Spec defining the same variable: planVariable('DEPLOY_ENV', 'production').
3. Apply the Spec (repository-stored or local) and observe the plan variable value in UI — it should show production as default but retain staging as override if you edit it post-apply.
4. Commit a change to the Spec (e.g., DEPLOY_ENV=qa) and watch the plan configuration log for auto-sync (repository-stored) or re-run manually (local).
5. Attempt to edit a Spec-generated artifact path in the UI — confirm it is read-only.

Recommendation

Use repository-stored Groovy DSL for all structural configuration (stages, jobs, tasks, default variables, artifact patterns). Reserve UI overrides for environment-specific values that differ per deployment target. Accept that artifact locations become code-controlled; if stakeholders need to tweak paths frequently, keep those definitions in the UI and only version-control the build logic.

Uncertainty flag: The exact behavior of variable override preservation during Spec re-application may vary between Bamboo 8.x and 9.x. Verify with your version before committing to a strategy.