Adopting Bamboo Specs as Code for Multi-Job Plans with Artifact Sharing

The Problem: UI-Driven Plans Break Reproducibility

Teams managing Bamboo plans through the web UI face a familiar drift: a colleague tweaks a task, someone renames an artifact, and the next build fails because downstream jobs still expect the old name. The plan works on one branch but not another because the UI changes weren't propagated. Bamboo Specs solves this by moving plan definition into version-controlled YAML that lives alongside your source code. When you commit a spec change, Bamboo imports it automatically—every build runs against a known, reviewable configuration.

Desired Outcome

A reproducible Bamboo plan defined in a specs repository that imports automatically on commit, builds source, runs tests, publishes immutable artifacts with fingerprints, and promotes them to downstream jobs—all without manual UI edits after the initial setup.

Prerequisites

• Bamboo Server or Data Center 7.x or 8.x with Specs support enabled (Administration → Specs → Enable Specs).
• Git repository readable by Bamboo (HTTPS with token or SSH key configured on the Bamboo server).
• Service account with Plan Administration permissions on the target project and read access to the specs repo.
• Existing plan in Bamboo configured to point at the specs repository and branch (Plan → Specs → Link to repository).

Verify the service account can clone the repo from the Bamboo server host before proceeding.

Focused Procedure: Define the Spec

Create bamboo-specs/bamboo.yml (or bamboo-specs.yaml at repo root) in your specs repository. The following example defines a plan with two jobs—build produces a JAR artifact, and integration-test consumes it.

version: 2
project:
  key: DEMO
  name: Demo Project
plan:
  key: SPEC
  name: Specs-Driven Build
  repositories:
    - name: source
      url: https://git.example.com/team/app.git
      branch: main
      authentication: service-account-token
  jobs:
    - build:
        name: Build & Test
        tasks:
          - checkout:
              repository: source
          - script:
              interpreter: bash
              body: |
                ./mvnw -B package
          - artifact:
              name: app-jar
              pattern: target/*.jar
              location: target
              required: true
    - integration-test:
        name: Integration Tests
        requirements:
          - system.docker.executable
        artifacts:
          - name: app-jar
            sourcePlan: DEMO-SPEC
            sourceJob: build
        tasks:
          - checkout:
              repository: source
          - artifact-download:
              name: app-jar
              destination: target
          - script:
              interpreter: bash
              body: |
                docker run --rm -v $(pwd):/workspace maven:3.9-eclipse-temurin-21 \
                  mvn -f /workspace/pom.xml -DskipTests=false verify

Key Elements Explained

• version: 2 — Specs schema version; required for Bamboo 7.x+.
• repositories — Declared once at plan level; jobs reference by name.
• artifact (publish) — pattern uses Ant-style glob; location is relative to working directory. required: true fails the job if no files match.
• artifacts (consume) — sourcePlan uses the plan key (project-plan), sourceJob matches the producer job key. Bamboo fingerprints the artifact at publish time; downstream jobs download the exact fingerprinted file.
• requirements — Ensures the agent has Docker for the integration test container.

Triggering the Import

Commit and push the file to the branch your plan watches (e.g., main). Bamboo polls every 60 seconds by default, or you can configure a webhook in your Git host to hit https://bamboo.example.com/rest/api/latest/specs/webhook for near-instant import.

Expected Checks After Import

1. Plan imported successfully — Open the plan in Bamboo, go to the Specs tab. Confirm "Last imported commit" shows your commit SHA and "Validation errors" is empty.
2. Jobs execute in order — Trigger a manual build. The build log should show build completing before integration-test starts.
3. Artifacts published with fingerprints — In the build job log, look for lines like Publishing artifact [app-jar] with fingerprint [sha256:...]. The artifact appears under the build's Artifacts tab with the correct name.
4. Downstream job receives artifact — In the integration-test log, verify Downloading artifact [app-jar] from build [DEMO-SPEC-123] succeeds and the file appears at target/app-1.0.0.jar (or whatever the pattern matched).
5. Plan history shows spec version — Each build result lists the Specs commit SHA under "Specs version" so you can trace exactly which YAML produced the build.

Recovery Options

When a spec change breaks the plan:

• Revert the offending commit — git revert <sha> && git push. Bamboo re-imports the previous spec on next poll/webhook and the plan returns to a working state.
• Temporarily disable Specs — Plan → Specs → Disable Specs. This lets you edit the plan via UI to unblock a release. Re-enable Specs after the fix is committed; the next import will overwrite UI changes.
• Restore from Bamboo backup — If the plan definition was corrupted beyond Git history, restore a plan export from Bamboo's scheduled backups (Administration → Backup).
• Test in a plan branch first — Create a plan branch (Plan → Branches → Create branch) pointing at a feature branch in the specs repo. Validate the spec there before merging to main.

Limitations and Gotchas

• Specs overrides UI — Any manual change made in the Bamboo UI after Specs is enabled will be lost on the next import. Treat the YAML as the single source of truth.
• Artifact immutability — If you rename an artifact or change its path in the producer job without a new build, downstream jobs fail because they request the old fingerprint. Always publish a new artifact from a successful build before updating the consumer spec.
• Permissions cause silent import stalls — If the service account loses read access to the specs repo, the plan sits in "Importing" state with no error in the UI. Check the Bamboo application logs (atlassian-bamboo.log) for authentication failures.
• Version-sensitive syntax — Bamboo 8.x introduced changes to task keys (e.g., script vs bash) and deprecated some task types. Validate your spec against the target version's documentation before upgrading.

Practical Verification Checklist

Run through this after any spec change:

1. Open the plan → Specs tab → confirm commit SHA and zero validation errors.
2. Run a manual build → watch job logs for artifact publish/download steps completing with expected filenames.
3. Check the build's Artifacts tab → verify the published JAR name matches the pattern.
4. Review the plan audit log (Plan → Audit log) → confirm the build used the intended specs commit.
5. Inspect the downstream job's working directory (via log or SSH to agent) → confirm artifact downloaded to the declared destination.

Rollback Note

Rollback is inherent to the Git workflow: git revert creates a new commit that undoes the change, triggering a fresh import. No separate Bamboo rollback operation is needed because the plan state is derived from the spec at import time.