Promote Build Artifacts Across Environments Using Bamboo Deployment Projects

Problem and takeaway

A build plan can produce a tested artifact, but nothing in the plan itself stops that same artifact from being rebuilt or redeployed inconsistently across Development, Staging, and Production. Teams often end up running separate builds per environment, which breaks the principle of promoting a single verified binary.

Useful takeaway: model promotion separately from the build with a Bamboo Deployment Project. Link the build plan’s artifact, add environments, and gate Production behind a manual approval task so authorized users can approve or reject without plan administration rights.

Desired outcome

After this procedure, a successful build in a source plan creates a deployable release. That release can be deployed to Development automatically, promoted to Staging after a check, and held at Production until an assigned approver manually approves it. Deployment history records the build number, artifact version, user, and outcome for each environment.

Prerequisites

• Bamboo Server or Data Center with Deployment Projects licensed and enabled. UI paths and licensing differ between editions; verify your installed version.
• A build plan that explicitly generates and shares artifacts. Artifacts must exist in a plan result before a deployment project can select them.
• A Bamboo user with permission to create or edit deployment projects and to assign environment-level permissions.
• At least one non-admin user who should hold production approval rights.

Version assumption: steps describe Bamboo’s standard Deployment Projects UI. Major releases can change capabilities, so verify against your version before following the procedure.

Procedure

1. Create the deployment project and environments

1. In Bamboo, go to Deployment projects and create a project, for example MyApp Release Promotion.
2. Add environments in promotion order: Development, Staging, Production.
3. Link the source build plan and select the artifact to deploy, such as myapp-1.0.0.zip or a Docker image reference.

2. Configure environment permissions

1. Open each environment’s permissions.
2. Grant Deployment use to the team that deploys to Development and Staging.
3. Grant Approve to specific users or groups for Production, but not necessarily Administer. This lets them approve or reject a manual gate without changing plan configuration.

3. Add a manual approval gate to Production

1. Edit the Production environment.
2. Add a manual task before the deployment task.
3. Set the task to require approval from users with the Production Approve permission.
4. Save the environment.

4. Deploy and promote

1. Create a deployment from the latest successful build result.
2. Deploy to Development. Verify the artifact version and build number appear on the environment dashboard.
3. Promote the same release to Staging.
4. Promote to Production. The deployment pauses at the manual approval task.
5. An authorized approver opens the deployment, reviews the artifact version and build logs, then selects Approve or Reject.

Configuration example: Bamboo Specs

Bamboo Specs lets you define deployment projects as code in a version-controlled repository. The following snippet illustrates structure only; adapt class names, imports, and method calls to your Bamboo Specs version.

// Example only; not a complete compilable class.
DeploymentProject myApp = new DeploymentProject()
    .name("MyApp Release Promotion")
    .planKey("MYAPP-BUILD")
    .environments(
        new Environment("Development").automaticDeploy(true),
        new Environment("Staging").automaticDeploy(false),
        new Environment("Production")
            .manualApproval(true)
            .approvers(group("production-approvers"))
    );

Expected checks

• Environment dashboard shows the deployed build number, artifact version, deploying user, and success status.
• Production deployment remains pending until a user with Approve permission acts on the manual gate.
• Deployment history lists the artifact version, build number, user, and outcome per environment.
• Deployment logs show the exact task that succeeded or failed.

Recovery and rollback

Deploying changes state, so have a recovery path before promoting to Production.

• Rollback method: redeploy an earlier artifact version to the same environment. Bamboo does not automatically reverse database migrations, external configuration changes, or data updates made by the failed deployment.
• Before redeploying, confirm the older artifact is still available and compatible with the current database schema.
• Check the deployment history to identify which build number and artifact version was last known good.

Limitations

• Missing deployment permissions block promotion or approval even for users who can run builds.
• Artifacts must be explicitly generated and shared by the build plan; a deployment project cannot select an artifact that was not published.
• Redeploying an older artifact is not a guaranteed rollback of stateful changes such as schema migrations.
• Feature names, UI paths, and licensing behavior differ between Bamboo Server and Data Center editions.

Practical verification

1. Create a test Deployment Project with Development and Production environments.
2. Link a build plan artifact and deploy to Development.
3. Assign a non-admin user Deployment use and Approve on Production.
4. Attempt a Production deployment as that user and confirm it pauses at the manual gate.
5. Approve or reject, then inspect deployment logs and history for the exact artifact version.