skip to content

Repository Promotion

One built artifact moves from a staging repository to a release repository without a rebuild. Interviewers ask how that move is made, recorded and restricted, and what it does to tags.

on this pageshow

questions

6

In a repository manager, what are staging and release repositories, and what does promoting an artifact between them mean?

level: juniorimportance: must knowfreq 62%

answer

  1. two repositories, two levels of trust
  2. candidate builds land first
  3. same bytes, new place or status
  4. release side locked to few writers
  5. close, then release or drop

basics

~10 s

A staging repository holds candidate builds still under test; a release repository holds only approved versions. Promotion puts the exact same artifact into the release repository, or marks it released, without rebuilding it.

solid answer

~40 s

CI deploys every candidate build to a **staging** repository, where testers and test pipelines resolve it. When a build passes QA it is **promoted**: the repository manager places the identical bytes in the **release** repository, by copying or moving them, or marks the artifact released with metadata, and records who did it and when. Nothing is rebuilt, so the checksum QA tested is the checksum that ships. The release repository is usually locked down: few identities may write to it, and it is configured to refuse overwriting a published version. A rejected candidate is dropped from staging and never reaches release. Maven's own release procedure is a familiar example: artifacts go into a Nexus Repository staging repository, which is closed for a vote and then promoted or dropped.

go deeper

for a junior

Recall the two roles: staging holds candidates that are still being tested, release holds only approved versions, and promotion moves the same artifact across without rebuilding it.

for a middle

Explain the three ways a repository manager promotes (copy, move, metadata) and why the release repository gets tighter write access and overwrite protection than staging.

for a senior

Show you can prove what shipped: the checksum or digest QA tested must equal the one in release, and you know where the repository manager records who promoted it.

for a principal

Frame staging versus release as a trust boundary the organisation enforces through permissions, immutability and retention, and weigh how many such repositories every team must run.

## Two repositories, two promises A **repository manager** (Artifactory, Nexus Repository, Harbor and similar products) stores the outputs of builds: Maven artifacts, npm and PyPI packages, NuGet packages, Helm charts, container images. Most teams split those outputs into at least two kinds of repository: - A **staging repository** holds **candidate** builds. CI writes to it freely, test environments read from it, and most of what lands there is never released. - A **release repository** holds only **approved** versions. Production builds and deployments resolve from it, and it is written to rarely and on purpose. The point of the split is that each repository makes one promise. Staging promises nothing beyond "a build produced this". Release promises "this exact artifact was tested and approved". Keeping them apart lets you give each one different permissions, a different overwrite rule and a different cleanup policy. ## What promotion does **Promotion** is the act that moves an approved candidate from the first promise to the second. A typical flow: 1. CI builds once and deploys the artifact to staging, where the repository records its **checksum** (for an OCI image, its **digest**). 2. Test environments resolve that artifact from staging and QA signs it off. 3. A promotion step asks the repository manager to place the **same bytes** in the release repository, or to mark the artifact as released. 4. Consumers that resolve from the release repository can now see it. The critical property is that **nothing is rebuilt**. A rebuild produces a new artifact with a new checksum that nobody has tested. Promotion keeps the checksum QA saw, so the release repository can prove it holds what was approved. The repository manager can perform the move in three ways, which are worth knowing by name: **copy** (the artifact now exists in both repositories), **move** (it leaves staging), or **property- or label-based** promotion (it stays where it is and its metadata changes to say it is released). Each has different costs for storage, audit and consumers. ## The same idea in each product's words | Product | Where candidates live | Where releases live | How a promotion is usually made | |---|---|---|---| | Artifactory | a local repository named for its stage, such as `payments-maven-dev-local` | a local repository for the release stage | copy or move between local repositories, or a property on the artifact | | Nexus Repository | a staging repository | a hosted release repository | the staging repository is closed, then promoted or dropped, as in Maven's release procedure | | Harbor | a project such as `develop` | a project such as `release` | copying an artifact between projects, e.g. `develop/app:v1.0` to `release/app:v1.0` | Artifactory's own naming guidance builds the stage into the repository name: `<team>-<tech>-<maturity>-<locator>`, where **maturity** is a stage such as `dev`, `qa` or `prod`. That makes the promotion path visible in the repository list itself. ## Staging repositories in Maven's own release procedure Maven's project documents a concrete version of this pattern. The release is deployed into a **staging repository** in Nexus Repository. The staging repository is then **closed** with a message naming the vote, and the vote email links to it so reviewers can test the exact artifacts. If the vote passes, the staged release is **promoted** to the production repository; if it fails, the staging repository is **dropped** and nothing reaches users. The same build is voted on and released, which is the whole idea. ## What makes the release repository trustworthy Promotion only means something if the release repository is harder to write to than staging: - **Write access** to release is limited to a promotion identity or a small group, while CI keeps write access to staging only. - **Overwrite protection**: the release repository is configured to refuse a second upload of a version that already exists, and container registries can make release tags immutable. - **A record**: the repository manager keeps who promoted what and when, and often a property or label on the artifact naming the build and approval. - **Separate cleanup**: staging can be cleaned aggressively because only release holds what production needs. ## Common misunderstandings - Promotion is not a rebuild with a release flag; a rebuild breaks the link to what was tested. - A staging repository is not the same thing as a snapshot repository. Snapshots are a Maven versioning mechanism for builds in progress; a staging repository holds release-numbered candidates waiting for approval. - A release repository does not become immutable by being called "release"; the overwrite rule is a setting someone has to turn on. - Promotion is a repository operation. Which environment then deploys the promoted artifact is a delivery-pipeline question, not something the repository decides.

  • Why not let consumers read directly from the staging repository once a build is approved?
    Because staging makes no promise. It holds every candidate, including failed ones, CI can overwrite or clean it at will, and its permissions are loose. A consumer pointed at staging could resolve an unapproved build. The release repository exists so that "I resolved it from release" is itself evidence the artifact was approved.
  • Is a staging repository the same thing as a Maven snapshot repository?
    No. A snapshot repository holds in-progress builds with SNAPSHOT versions that are expected to change. A staging repository holds release-numbered candidates that should never change, waiting for approval. A candidate that fails approval is dropped from staging; it is not replaced by a newer snapshot.

Like a publisher's proofs table and the bookshop shelf: the approved print run is moved to the shelf as printed, never re-typeset after the proofreader signed it off.

  • Promotion means rebuilding the release from the approved commit.
  • Staging and snapshot repositories are the same thing.
  • Naming a repository release makes its versions immutable automatically.
  • Production should resolve from staging once QA approves the build.
  • A failed candidate should be fixed in place inside staging.
open as a page

In a repository manager, how do copy, move and property-based promotion differ in storage, audit trail and what consumers can resolve?

level: middleimportance: must knowfreq 50%

basics

~20 s

Copy leaves the artifact in staging and release; move takes it out of staging; property-based promotion leaves it in place and changes metadata that consumers must filter on. They differ in disk use, history kept and who can still resolve it.

open as a page

How should repository permissions be split so CI can deploy to a staging repository but only a promotion identity can write to release?

level: middleimportance: should knowfreq 45%

basics

~20 s

Give the CI identity write access to staging and only read access to release, and give a separate promotion identity read on staging and write on release, with no overwrite or delete there. The repository manager then logs every promotion.

open as a page

In an OCI registry, images are promoted by copying the stg tag to prd, and production ran an image QA never tested; what happened and how do you fix promotion?

level: seniorimportance: should knowfreq 48%

basics

~20 s

Copying a tag copies whatever digest it points to at copy time. CI pushed a newer build to stg after approval, so that build was promoted. Promote the approved digest into a release repository CI cannot write, with immutable tags.

open as a page

When standardising artifact promotion across a company, would you use one repository per stage or one repository with promotion metadata, and why?

level: principalimportance: should knowfreq 35%

basics

~20 s

Prefer a repository per stage as the enforcement boundary, because permissions, immutability and retention then attach to the repository; use metadata on top to record builds and approvals. Metadata-only promotion is lighter but depends on every consumer filtering correctly.

open as a page

In Harbor, QA labels an image as approved, but an event-based replication rule filtered on that label never pushes it to production; why?

level: seniorimportance: nice to knowfreq 25%

basics

~20 s

Harbor's event-based replication fires only on pushing, retagging and deleting artifacts; changing a label triggers nothing. The image was pushed before it had the label, so the filter excluded it then, and labelling it later never re-ran the rule.

open as a page