Promote a Drone CI Build to a Target Environment (2026)

Drone CI promotion is a way to move a built artifact from one environment to another, like from staging to production, without rebuilding it.

Let’s see it in action. Imagine you have a successful build in your staging environment. You want to promote that exact same build to your production environment.

Here’s a simplified drone.yml that defines a promotion:

kind: pipeline
type: docker
name: deploy-staging

steps:
  - name: build
    image: plugins/docker
    settings:
      repo: your-docker-repo/your-app
      tags:
        - ${DRONE_COMMIT_SHA}
        - latest

---
kind: pipeline
type: docker
name: deploy-production

trigger:
  event:
    - promotion # This is the key!

steps:
  - name: deploy
    image: your-custom-deploy-image # Or a standard one like appleboy/drone-ssh
    settings:
      # This is how you specify the exact build to promote
      repo: your-docker-repo/your-app
      tag: ${DRONE_COMMIT_SHA} # Using the SHA ensures we deploy the exact same artifact
      # ... other deployment settings (host, username, etc.)

When a build completes successfully on the deploy-staging pipeline, you can manually trigger a promotion. Drone will then look for a pipeline defined with trigger: event: - promotion. In our example, that’s deploy-production.

The crucial part here is tag: ${DRONE_COMMIT_SHA} in the deploy-production pipeline. When Drone initiates a promotion, it passes the commit SHA of the original build to the promoting pipeline. By using this SHA as the tag for the artifact you’re deploying, you guarantee you’re promoting the exact same Docker image (or other artifact) that was built and tested in the previous stage. This eliminates any possibility of the artifact changing between stages, a common source of "it worked on staging but not production" bugs.

The system in action:

1. Build & Test on Staging: A commit triggers the deploy-staging pipeline. It builds a Docker image, tags it with the commit SHA (e.g., a1b2c3d4) and latest, and pushes it.
2. Manual Promotion: You go to the Drone UI, find the successful build for deploy-staging with SHA a1b2c3d4, and click the "Promote" button, selecting deploy-production as the target.
3. Trigger Production Pipeline: Drone creates a new build for the deploy-production pipeline. It automatically sets the DRONE_COMMIT_SHA environment variable for this new build to a1b2c3d4.
4. Deploy Specific Artifact: The deploy-production pipeline executes. The deploy step uses repo: your-docker-repo/your-app and tag: ${DRONE_COMMIT_SHA} (which is a1b2c3d4). It pulls and deploys the Docker image tagged your-docker-repo/your-app:a1b2c3d4.

This mechanism effectively decouples the build process from the deployment process. The build pipeline is responsible for creating and testing a single artifact. The promotion mechanism then triggers separate deployment pipelines, each targeting a specific environment, to deploy that exact artifact.

The problem this solves is the "rebuild in production" anti-pattern. If you build your application once in staging and then trigger a new build in production with the same code, you’re not deploying the same artifact. Different build environments, different dependencies, even subtle differences in compiler versions could lead to a different outcome. Promotion ensures you’re moving the proven artifact.

The levers you control are primarily within your .drone.yml:

• trigger: event: - promotion: This is how you declare a pipeline as a promotion target.
• DRONE_COMMIT_SHA: This automatically provided environment variable is the key to referencing the original build’s artifact. You use it in your deployment steps to pull the specific version.
• Artifact Naming/Tagging: How you tag your artifacts in the build pipeline (e.g., using ${DRONE_COMMIT_SHA}) directly impacts how you reference them in the promotion pipeline.

The most surprising thing is how simply Drone handles the state transfer. It doesn’t move the artifact itself; it uses the commit SHA as a stable identifier. Your deployment pipeline, whether it’s deploying to a Kubernetes cluster, a server via SSH, or uploading to an S3 bucket, uses this SHA to fetch the exact same artifact that was built and validated in the preceding stage. This means your deployment script needs to be able to pull an artifact based on a specific tag or identifier, which is a standard practice.

The next concept you’ll run into is managing different promotion paths and environments, perhaps using Drone’s named environments or more complex trigger conditions.