Skip to main content
In modern CI/CD pipelines, ensuring consistency across environments is critical. Docker Trusted Registry (DTR) enables you to build once and promote the identical Docker image through dev, test, staging, and production—eliminating rebuilds and version drift.

​
Environment Isolation and Traditional Workflows

Organizations often isolate each deployment stage:
  • Separate clusters or infrastructure for dev, test, staging, and prod
  • Distinct Docker registries or accounts per environment
A typical multi-stage pipeline without image promotion:
  1. Build the Docker image in development
  2. Deploy and test
  3. Push code to test, triggering a fresh build
  4. Deploy in test; repeat build-deploy in staging
  5. Rebuild and deploy in production
Rebuilding at each stage can introduce unintended changes—updated package versions, OS patches, or dependency drift—undermining the reproducibility of your pipeline.
StageActionDrawback
DevelopmentBuild & initial testUnique image per build
TestNew build & deployVersion drift risk
StagingFresh rebuild & deploySlow feedback loop
ProductionFinal rebuild & deployInconsistent with earlier stages
The image illustrates a "Development Pipeline" with four stages: Dev, Test, Stage, and Prod, each represented by a globe icon and a URL.

​
Benefits of DTR Image Promotion

By leveraging DTR promotions, you gain:
  • Single build for all environments
  • Guaranteed consistency (same image by digest)
  • Faster pipeline throughput
  • Simplified auditing and traceability

​
How DTR Image Promotion Works

  1. Build once in development and push to your dev repository.
  2. DTR automatically promotes that exact image (tag or digest) to test.
  3. After tests pass, the same image is promoted to staging.
  4. Upon approval, it moves to production—no rebuilds required.
Image promotion preserves the original digest, ensuring the exact artifact tested in QA reaches production.

​
Configuring Image Promotion in DTR

Navigate to your repository’s Promotion tab in the DTR UI to define rules:
ConfigurationDescriptionExample
Source triggerTag name or digest that initiates promotionstable, sha256:...
ConditionMatching rule (equals, starts with, regex)starts with "v1.2."
Target registryDestination repository or registry (same or different)registry.company.com/test
Once set, any image pushed with a matching tag is automatically copied to your target repository.
The image shows a software interface for managing image promotions, with options to set tag names and conditions like "equals," "starts with," and others. The interface includes buttons for canceling or adding the promotion.

​
Next Steps

We’ll now demonstrate setting up and using image promotions in a live DTR instance, covering:
  • Access control and permissions
  • Complex promotion filters
  • Rollback strategies

​
References

Watch Video