Deploying Artifacts Across Environments in Bamboo: A Practical Guide to Release Versioning and Rollbacks

What You’ll Achieve

By the end of this guide you will have a Bamboo deployment project that:

• Promotes the same versioned artifact from QA to Staging to Production.
• Uses release versioning so you can roll back to a known good build without rebuilding.
• Enforces environment‑specific permissions and agent capability matching.
• Provides clear audit logs for every promotion step.

Prerequisites

• Running Bamboo Data Center or Server (Cloud is no longer supported).
• Admin or Deployment Project editor permissions.
• At least one build plan that compiles, tests, and packages your application.
• Agents with the required capabilities (e.g., deploy, tomcat, ssh).
• Artifact sharing enabled in the build plan.
• REST API access if you prefer scripting (API token or basic auth).

Step‑by‑Step Procedure

1. Define a Versioned Artifact in Your Build Plan

Open the build plan’s Artifacts tab and add a new artifact definition. Use a filename pattern that includes the build number, e.g., app-${bamboo.buildNumber}.jar. Set the artifact to be shared and published so it’s available to deployment projects.

Example REST call to create the artifact (replace placeholders):

POST /rest/api/latest/plan/{projectKey}-{planKey}/artifact
{
  "artifactName": "AppJar",
  "artifactPath": "build/libs/app-${bamboo.buildNumber}.jar",
  "shared": true,
  "publish": true
}

Verify by navigating to the plan’s Artifacts page and confirming the entry appears.

2. Set Artifact Retention Policy

Under Artifact Retention choose a policy that keeps artifacts long enough for rollbacks (e.g., keep the last 10 builds). Aggressive cleanup will delete the artifact before a rollback can occur.

3. Create a Deployment Project

Navigate to Deployments → Create deployment project. Give it a name, e.g., MyApp Deployments, and link it to the build plan you just configured.

Enable Deployments from a specific build result so the deployment is tied to a release version.

4. Add Environments

Within the deployment project, add three environments: QA, Staging, and Production. For each environment:

• Define Agent Requirements (e.g., deploy=true).
• Set Trigger type:
  • QA: Automatic after build success.
  • Staging: Manual with approval.
  • Production: Manual with double approval.
• Configure tasks. Typical tasks include:
  • Download artifact (auto‑populated).
  • Run a shell script to deploy (e.g., ./deploy.sh app-${bamboo.buildNumber}.jar).
  • Health‑check HTTP request to confirm deployment.

5. Deploy a Release

From the Bamboo UI, open the deployment project and click Deploy a release. Select the build number you want to promote. Bamboo will create a release version (e.g., release-2026.10.14-001) that ties the artifact to that specific build.

After the QA environment completes, use the Promote button to move the same release to Staging, then to Production. Each promotion is recorded as a separate deployment record.

6. Rollback to a Previous Release

To rollback, navigate to the deployment project, locate the earlier release (e.g., release-2026.10.10-001), and click Deploy a release again. Choose the target environment (Production) and confirm. Bamboo will redeploy the same artifact without rebuilding.

7. Verify Deployment Success

• Check the deployment log for the target environment; look for Deployment Successful and the agent name.
• Run a simple health‑check script (curl to /health endpoint) to confirm the service is up.
• Review the Deployment History for the environment to ensure the release version matches the intended one.

8. Recover from a Missing Artifact

If a deployment fails due to a missing artifact, the log will show Artifact not found. To recover:

1. Verify the artifact still exists in the build plan’s artifact list.
2. If it’s been cleaned up, rebuild the original build or restore from backup.
3. Re‑run the deployment for the environment that failed.

Limitations & Caveats

• Artifact retention policies are global per plan; you may need to adjust them if you have short‑term build retention.
• Deployment projects do not automatically trigger on every build; you must configure triggers or manually deploy.
• Permissions are granular but can become complex; audit the Deployment Project Permissions to ensure only authorized users can approve production deployments.
• REST API calls require the same authentication as the UI; ensure your token has read and write scopes for deployment resources.

Practical Check

After completing the steps, run the following sanity check:

curl -u user:pass "${bamboo.baseUrl}/rest/api/latest/deploy/project/{projectKey}-{deploymentKey}/environment/{envKey}/deployments?maxResult=1"

Inspect the JSON for a deploymentResult with status=SUCCESS and the expected releaseVersion. If the status is FAILED, review the log for agent capability mismatches or missing artifacts.

Summary

By separating build plans from deployment projects, Bamboo lets you promote the same artifact across multiple environments, enforce release versioning, and roll back quickly. The key is to define artifacts correctly, set sensible retention policies, and use environment triggers that match your team’s approval workflow.