Skip to content

docs QCI-only promotion behavior #614

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-bot merged 1 commit into from
Aug 10, 2026
+23 −38
Merged

docs QCI-only promotion behavior #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions content/en/architecture/ci-operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,11 @@ or `Namespace` so that other repositories can consume them. Publication to an in
there is a requirement to quickly identify all images that belong to a version; tags will take the form of `version:component`.
Publication to a `Namespace` creates tags in the form of `component:version` and may be more familiar to users.

The `promotion` stanza names destinations as ImageStream coordinates (`namespace` / `name` / `tag`). Under the hood,
promotion pushes image bits to **QCI** (`quay.io/openshift/ci`). Payload namespaces (`ocp`, `ocp-priv`, `origin`) also
update `app.ci` ImageStream tags as **source-refs** to those QCI digests; other namespaces are QCI-only. Pull published
images via `quay-proxy.ci.openshift.org` — see [How promotion works](/how-tos/use-registries-in-build-farm/#how-promotion-works).

Images are published for each `component` specified in `images[].to` unless explicitly excluded (see examples below).

Images published in this manner are produced when the source repository branch is updated (e.g.
Expand Down
40 changes: 14 additions & 26 deletions content/en/how-tos/use-registries-in-build-farm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,39 +42,35 @@ images are built on a build farm and [promoted](/architecture/ci-operator/#publi
copies they hold are up-to-date and jobs that run there run with the correct container image versions.

{{< alert title="Info" color="info" >}}
**Today (transitional):** `ci-operator` may still place tags on `app.ci`'s registry `registry.ci.openshift.org` for internal automation such as Release Controllers and [external mirroring](/how-tos/mirroring-to-quay/#mirror-images-with-wildcard). That path is shrinking — see [Coming soon: life after the QCI migration](#coming-soon-life-after-the-qci-migration).
Images are promoted to QCI. Payload namespaces keep `app.ci` ImageStream tags as source-refs for Release Controllers and related automation. See [How promotion works](#how-promotion-works).

ART still pushes builder images for CI to `app.ci` and they are [mirrored to QCI](https://github.com/openshift/release/blob/main/core-services/image-mirroring/_config.yaml).

**Rule of thumb for humans and integrations:** do not hardcode `registry.ci.openshift.org` for CI-published images. Pull from QCI via `quay-proxy.ci.openshift.org` instead.
{{< /alert >}}

# Coming soon: life after the QCI migration
# How promotion works

{{% alert title="Coming soon" color="info" %}}
This section describes the **intended end state** of the QCI migration. Pieces are landing over time in `ci-tools` / `openshift/release`. Until a change is fully rolled out, behavior may still look like the transitional setup above. When in doubt, treat **QCI + quay-proxy** as the place you pull from.
{{% /alert %}}
Quay holds the image bits for CI (`quay.io/openshift/ci`). `app.ci` is not a second full copy of every promoted image.

In plain terms: we are finishing the move so that **Quay holds the real image bits** for CI, and `app.ci` stops being a second copy of every promoted image. Your day-to-day as a component owner stays simple; most of the complexity is platform plumbing.
## For component owners

## What stays the same for you

| You still… | Unchanged details |
| Task | Details |
|---|---|
| Declare `promotion:` in `ci-operator` config | Same YAML shape (`namespace` / `name` / `tag`). You do not rewrite promotion stanzas for QCI. |
| Declare `promotion:` in `ci-operator` config | Same YAML shape (`namespace` / `name` / `tag`). No special QCI fields. |
| Pull published images via quay-proxy | `quay-proxy.ci.openshift.org/openshift/ci:<namespace>_<name>_<tag>` after logging in with an `app.ci` token (see below). |
| Reference ImageStream-style names in config | `base_images`, `from:`, Dockerfile `FROM registry.ci…` entries continue to resolve through CI to the QCI float. |
| Debug a live job’s builds | Ephemeral build-farm registries (`registry.buildNN…`) for `ci-op-*` namespaces stay as they are today. |
| Reference ImageStream-style names in config | `base_images`, `from:`, Dockerfile `FROM registry.ci…` entries resolve through CI to the QCI float. |
| Debug a live job’s builds | Ephemeral build-farm registries (`registry.buildNN…`) for `ci-op-*` namespaces. |

## What changes under the hood
## Where images go

Think of three buckets of images:

1. **Payload / release-facing images** (namespaces such as `ocp`, `ocp-priv`, and OKD’s `origin`)
Promotion pushes the image **to QCI**. On `app.ci`, ImageStream tags remain so Release Controllers and related automation can keep working — but those tags are **references** (source-refs) to the QCI digest, not a second full blob store of every layer on `registry.ci.openshift.org`.

2. **Everything else (non-payload CI images)**
Promotion becomes **QCI-only**. No new ImageStream tags / blob copies are created on `app.ci` for those images. If you used to peek at `registry.ci.openshift.org/<your-ns>/…` after merge, that path goes away; use quay-proxy / QCI instead.
Promotion is **QCI-only**. No new ImageStream tags / blob copies are created on `app.ci` for those images. Pull via quay-proxy / QCI instead of `registry.ci.openshift.org/<your-ns>/…`.

3. **Emergency backfill (platform only)**
If something must temporarily reappear on `app.ci`, Test Platform can mirror **from QCI only** onto `registry.ci.openshift.org` via the `qciToAppCIImages` list in [image-mirroring `_config.yaml`](https://github.com/openshift/release/blob/main/core-services/image-mirroring/_config.yaml). Arbitrary registries are not allowed as sources for that reverse path.
Expand All @@ -100,37 +96,29 @@ Think of three buckets of images:
### Component owner who promotes images

1. Merge a PR that builds and promotes (or wait for the periodic / postsubmit `images` job).
2. Wait for the promote step to finish successfully on QCI (failures show up in the Prow job log as they do today).
2. Wait for the promote step to finish successfully on QCI (failures show up in the Prow job log).
3. Pull what you need:

```bash
podman login -u=$(oc --context app.ci whoami) -p=$(oc --context app.ci whoami -t) quay-proxy.ci.openshift.org --authfile /tmp/t.c
podman pull quay-proxy.ci.openshift.org/openshift/ci:<namespace>_<name>_<tag> --authfile /tmp/t.c
```

4. **Do not** assume a fresh `oc get istag -n <ns>` on `app.ci` exists for non-payload images after this migration. For payload namespaces, the ImageStream tag may still exist, but the storage behind it is QCI.
4. **Do not** assume a fresh `oc get istag -n <ns>` on `app.ci` exists for non-payload images. For payload namespaces, the ImageStream tag may still exist, but the storage behind it is QCI.

### Someone writing a Dockerfile or `base_images` entry

Keep using the familiar names (`ocp/4.x:…`, `ci/…`, builder tags, and so on). CI rewrites / imports those to the QCI float at job time. Prefer documenting quay-proxy pullspecs in READMEs and runbooks aimed at humans.

### Someone integrating automation (bots, mirrors, dashboards)

- **Read path:** authenticate to quay-proxy with an `app.ci` ServiceAccount (same RBAC model as today).
- **Read path:** authenticate to quay-proxy with an `app.ci` ServiceAccount (same RBAC model as elsewhere on `app.ci`).
- **Write path to QCI:** reserved for CI promotion and Test Platform tooling — not for ad-hoc user pushes.
- **Write path to `registry.ci.openshift.org` for “put this QCI image back on app.ci”:** only through the controlled reverse-mirror config, not by pointing promotion at an arbitrary external registry.

### Release / payload consumers

Release Controllers and similar consumers continue to use `app.ci` ImageStreams in payload namespaces. Those streams stay meaningful; they track QCI rather than hosting a duplicate blob tree for every tag.

## Docs and runbooks to update when this lands

When the migration finishes rolling out, refresh any page or SOP that still says:

- “Promotion always pushes blobs to both QCI and `registry.ci.openshift.org`.”
- “Check `registry.ci.openshift.org/<component-ns>/…` for the latest promoted image” (non-payload).
- Examples that use `registry.ci.openshift.org/ci/…` as the **authoritative** pull location for CI tools images — prefer quay-proxy / QCI.
Release Controllers and similar consumers use `app.ci` ImageStreams in payload namespaces. Those streams track QCI rather than hosting a duplicate blob tree for every tag.

Related deeper background: [Images in CI](/internals/images-in-ci/) (platform internals).

Expand Down
16 changes: 4 additions & 12 deletions content/en/internals/images-in-ci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,22 +84,14 @@ However, the additional layers of components on top of `QCI` might increase the
## The Integrated Image Registry on APP.CI

The integrated image registry on `app.ci`, `registry.ci.openshift.org`, had been the authoritative central CI registry
before `QCI` took over that role.

**Today (transitional):** promoted images may still appear on `app.ci` so Release Controllers and a few other internal
consumers keep working. Humans and integrations should still pull from [QCI via quay-proxy](/how-tos/use-registries-in-build-farm/),
not treat `registry.ci.openshift.org` as the source of truth.

{{% alert title="Coming soon" color="info" %}}
**After the QCI migration completes:**
before `QCI` took over that role. Humans and integrations pull from [QCI via quay-proxy](/how-tos/use-registries-in-build-farm/);
do not treat `registry.ci.openshift.org` as the source of truth.

- **Non-payload** promotion is QCI-only — no new app.ci ImageStream tags / blob copies for those images.
- **Payload** namespaces (`ocp`, `ocp-priv`, `origin`) keep app.ci ImageStream tags, but as **references to QCI digests** (source-refs), not a second full copy of every layer on `registry.ci.openshift.org`.
- **Payload** namespaces (`ocp`, `ocp-priv`, `origin`) keep app.ci ImageStream tags as **references to QCI digests** (source-refs), not a second full copy of every layer on `registry.ci.openshift.org`.
- **Emergency only:** Test Platform can backfill a tag from QCI onto app.ci via `qciToAppCIImages` in the [ci-images-mirror config](https://github.com/openshift/release/blob/main/core-services/image-mirroring/_config.yaml); sources must be QCI / quay-proxy, never an arbitrary registry.

For a layman walkthrough of what users do day-to-day, see [Coming soon: life after the QCI migration](/how-tos/use-registries-in-build-farm/#coming-soon-life-after-the-qci-migration).
{{% /alert %}}

User walkthrough: [How promotion works](/how-tos/use-registries-in-build-farm/#how-promotion-works).

## Troubleshooting

Expand Down