Versioning & Promotion Strategies

In one line

Promotion is moving one specific, already-built, already-tested artifact forward through environments deliberately — the deployment-pipeline expression of Topic 5.1's build-once principle, tied together with real version numbers.

0/4 · 0%

Key ideas

01
PROMOTION is the practice of moving ONE SPECIFIC artifact (identified by its unique version) forward through a sequence of environments — dev, then staging, then production — as it passes each environment's own checks, rather than deploying separately-built artifacts to each one independently.
02
This is Topic 5.1's build-once principle made fully concrete and operational: the artifact that reaches production is provably the EXACT SAME one that was validated in staging immediately before it, which was itself the exact same one that passed automated tests immediately before THAT — an unbroken, traceable chain from one single build all the way to production.
03
SEMANTIC VERSIONING (Git's own course, Phase 6.3, already covered MAJOR.MINOR.PATCH in depth) is the standard way to give a promoted artifact a genuinely meaningful, human-readable identity — but many real pipelines ALSO tag with a build number or commit SHA (Topic 5.3) specifically for perfect, unambiguous traceability back to the exact source and pipeline run that produced it, even when several builds might share the same semantic version during active development.
04
A genuinely common real promotion workflow: an artifact is automatically promoted from dev to staging once it passes its automated test suite, but promotion from staging to production requires an explicit, manual approval (directly connecting to Phase 2.2's GitHub Environments and Phase 4.3's GitLab when: manual) — automating the low-stakes step while keeping deliberate human judgment on the highest-stakes one.
05
ARTIFACT METADATA (which commit produced it, which tests it passed, when and by whom it was promoted) traveling WITH the artifact through this entire process is what makes a genuine, trustworthy AUDIT TRAIL possible — during an incident, being able to answer 'exactly what code is running in production, and what did it pass to get here' quickly and with total confidence is precisely what a well-designed promotion process provides.
06
This entire idea connects directly forward to Kubernetes' own course (Phase 8.4's GitOps preview) and this course's earlier Phase 4 (Deployment Strategies) — promotion is fundamentally about WHICH validated artifact moves to which environment, while a deployment strategy (rolling, blue-green, canary) is about HOW that artifact actually replaces what's currently running there; the two are genuinely complementary concerns, not competing ones.

Code & diagrams

PromotionChaindiagram

One artifact, one identity, moving forward through gates — never rebuilt, never replaced with something merely similar.

Rendering diagram…

promotion-pipeline.ymlmarkdown

Automatic promotion up to staging; a deliberate, manual gate for the final step to production.

stages:
  - build
  - test
  - promote-staging
  - promote-production

build:
  stage: build
  script:
    - export VERSION=1.5.0-${CI_COMMIT_SHORT_SHA}
    - mvn clean package
    - docker build -t my-registry/myapp:${VERSION} .
    - docker push my-registry/myapp:${VERSION}
    - echo "VERSION=${VERSION}" >> build.env
  artifacts:
    reports:
      dotenv: build.env    # passes VERSION forward to later stages automatically

promote-staging:
  stage: promote-staging
  script:
    - echo "Promoting ${VERSION} to staging — same artifact, no rebuild"
    - ./deploy.sh staging my-registry/myapp:${VERSION}

promote-production:
  stage: promote-production
  when: manual                # deliberate human gate for the highest-stakes step
  script:
    - echo "Promoting ${VERSION} to production — same artifact throughout"
    - ./deploy.sh production my-registry/myapp:${VERSION}

Explain it without notes

Why does a well-designed promotion pipeline pass the exact same VERSION identifier forward through every stage, rather than each stage computing or building its own?

Why is it a genuinely reasonable, common pattern to automate promotion to staging but require manual approval for promotion to production, rather than treating both identically?

Practice

Design (in plain English, or as real pipeline YAML) a promotion flow for a hypothetical application with dev, staging, and production environments, deciding which promotions should be automatic and which should require manual approval.

For a real or hypothetical incident ('something's broken in production'), write the exact question a good promotion/audit trail should let you answer within seconds, and what specific piece of tracked metadata would answer it.

Trade-offs

↔
A fully automated promotion pipeline (including all the way to production) is the fastest possible path from commit to live, but it requires genuinely trusting your automated tests completely, exactly as Topic 0.1 flagged for Continuous Deployment generally — a deliberate manual gate before production trades some of that raw speed for a real, human safety check, which is precisely why it remains the more common, more conservative choice for the majority of real production systems, even fairly mature ones.

Done when you can

I can explain what promotion means and how it makes Topic 5.1's build-once principle concrete and operational.
I can design a promotion pipeline that passes one consistent artifact identifier through every stage.
I understand why automating promotion to lower environments while gating production manually is a common, reasonable pattern.