Implementing Immutable Deployments in Bamboo via Artifact Promotion

The Problem: Environment-Specific Builds

Many teams mistakenly use separate Build Plans to deploy to different environments (for example, a Dev Build and a Prod Build). This approach introduces risk because the code is re-compiled or re-packaged for every environment, meaning the binary tested in QA is not identical to the one deployed to Production. This violates the principle of immutable artifacts.

The solution is to decouple the build from the release using Bamboo Deployment Projects. By building once and promoting the same artifact through a sequence of environments, you ensure that exactly what was verified in staging is what reaches your users.

Prerequisites

• Bamboo Server: Version 6.0 or later (Deployment Projects are a core feature of the server license).
• Build Plan: An existing Build Plan that produces a versioned artifact.
• Network Access: A Bamboo agent with SSH or API access to the target deployment servers.
• Permissions: Administrative access to create and link Deployment Projects.

Defining the Artifact in the Build Plan

Before creating a deployment project, the Build Plan must be configured to save the output. In the Build Plan configuration, navigate to the Artifacts tab and define the path to the files (for example, target/*.war or dist/app.zip) and give the artifact a descriptive name, such as Application-Binary.

Configuring the Deployment Pipeline

1. Create the Deployment Project

Go to Create > Deployment Project. Link this project to the Build Plan created in the previous step. This link tells Bamboo which build results are eligible to become Releases.

2. Define the Environment Sequence

Create environments in the order of your promotion path. For example:

• Development: Immediate deployment for integration testing.
• QA/Staging: Pre-production validation.
• Production: Final release to users.

Bamboo enforces a sequential flow; a release must typically succeed in Development before it can be promoted to QA.

3. Configure Deployment Tasks

Within each environment, add tasks to handle the artifact distribution. A common pattern is the SSH Task. Run the deployment script on the target server through the Bamboo agent; the agent needs SSH access and permission to restart the service.

• Host: The target server IP or hostname.
• Command: A script to stop the service, extract the artifact, and restart the service.

# Example deployment script executed via SSH Task
mkdir -p /opt/app/deployments/${bamboo.buildNumber}
cp /tmp/artifact.zip /opt/app/deployments/${bamboo.buildNumber}/
unzip /opt/app/deployments/${bamboo.buildNumber}/artifact.zip -d /opt/app/current
systemctl restart my-application

4. Automating Promotion

To reduce manual overhead, configure Release Triggers. You can set the project to automatically create a new release whenever the linked Build Plan completes successfully, or trigger a promotion to QA immediately after a successful Development deployment.

Comparison: Build-Based vs. Artifact-Based Deployment

Verification and Diagnostics

To verify the pipeline is functioning correctly, perform the following checks:

1. Artifact Presence: Check the Build Plan results. If no artifact is listed under the Artifacts tab, the Deployment Project will have nothing to deploy.
2. Release Status: In the Deployment Project dashboard, ensure the release status is marked as Successful (green). A Successful status indicates the tasks finished without returning a non-zero exit code.
3. Target Validation: SSH into the target server and run ls -l /opt/app/current to confirm the timestamp of the deployed files matches the Bamboo release time.

Limitations and Resource Management

Storage Pressure: Because Bamboo stores every versioned artifact to allow for rollbacks, your server disk can fill up quickly. Navigate to Plan Configuration > Artifacts and set a strict Artifact Retention policy (for example, keep only the last 10 successful builds) to prevent disk exhaustion.

Rollback Procedure

If a deployment to Production fails or introduces a bug, do not trigger a new build. Instead:

1. Navigate to the Deployment Project dashboard.
2. Locate the previous Successful release version.
3. Select Deploy on that specific version.

Bamboo will redeploy the previous immutable artifact, effectively reverting the environment to a known good state without requiring a code revert or re-compile.