> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/operations/deployment/helm-docker-versioning-and-ci/marking-a-known-good-build.md). # Marking a known-good build How to record that a develop build is known good, and have that note appear in the version catalogue — without tagging a release. Not every good build is a release. A build passes QA, gets deployed to a pilot, or is confirmed working against a particular integration — and none of that means you want to ship it. Tagging `N.N.N` would say "this is a supported, stable release", which is a different and much stronger claim. **Marking** records the weaker, more common statement: *this build is known good; you can rely on it.* No tag, no release, no rebuild. ## What it looks like The note appears in the **Notes** column of that module's catalogue page, rendered as markdown — so it looks exactly the way you wrote it: | Version | Date | Type | Notes | | ------------------- | ---------- | ------- | ----------------------------------------------------- | | `0.0.0-develop.207` | 2026-08-24 | develop | | | `0.0.0-develop.205` | 2026-08-21 | develop | **Intermediate Stable Version** — verified on staging | It also appears on that version's own section further down the page, directly under the heading: > **Note** — **Intermediate Stable Version** — verified on staging Releases keep their own section in the catalogue because they are tagged. A mark is only an annotation, so it stays in the table rather than creating a category of its own. {% hint style="info" %} **It applies retroactively.** The note is injected when the catalogue is rendered, not when the build ran — so you can mark a build from months ago and the note appears on its page immediately. Nothing is rebuilt and no artifact is touched. {% endhint %} ## How to mark a build Marks live in the **versions** repo ([`openg2p/versions`](https://gitlab.com/openg2p/versions)), in a file named `.marked` inside that module's folder. There is no pipeline and no form — it is a plain text file you edit directly. 1. Open the module's folder in the versions repo. The folder name is the project path with the group stripped and slashes flattened: * `openg2p/g2p-insights` → `g2p-insights` * `openg2p/registry/registry-platform` → `registry-registry-platform` * `openg2p/keycloak/keycloak-themes` → `keycloak-keycloak-themes` 2. Create or open `.marked` (**+ → New file** if it does not exist yet). 3. Add one line per marked version: ``` 0.0.0-develop.205|**Intermediate Stable Version** — verified on staging 1.3.0-rc.151|Passed the full QA cycle; safe for pilot deployments ``` 4. Commit to the versions repo's default branch. The format is `version|note`. The version must match the page exactly — `versions/0.0.0-develop.205.md` means you write `0.0.0-develop.205`. Everything after the first `|` is the note. The note is **markdown**, passed through as written: use `**bold**` if you want bold, `` `code` `` for a version or command, or a link. Nothing is added for you, so a plain note stays plain. A literal `|` inside a note is escaped automatically and cannot break the table row. The catalogue re-renders on every push to the versions repo, so the note appears on the site within a minute or so. You do **not** need to wait for the module's next build. {% hint style="info" %} **Editing and unmarking.** The note is meant to be revised — if you learn more later, edit the line. To unmark a build, delete its line. Both are ordinary commits to the versions repo. {% endhint %} ## What marking guarantees Two things happen automatically once a version is marked, and both exist so the mark cannot outlive the thing it points at: * **Retention no longer applies to it.** Develop pages are normally pruned after the newest 20 builds (see [Changelogs](/operations/deployment/helm-docker-versioning-and-ci/changelogs.md)). A marked page is exempt and stays until you unmark it. Without this, marking build 205 and doing nothing else would silently lose the note twenty builds later — exactly when you most want to look it up. * **Withdrawal refuses it.** [Withdrawing a version](/operations/deployment/helm-docker-versioning-and-ci/withdrawing-a-version.md) deletes a develop build's chart and images. It skips marked versions and says so. Deleting the artifact you told people was good is the mistake worth making impossible. Unmark it first if you really mean to withdraw it. ## What marking does *not* do * It does not tag anything, and does not create a Git tag, a GitLab Release, or a new version. * It does not rebuild, republish, or move any artifact. The image and chart are untouched. * It does not change what `develop` (the moving alias) points at. * It is not a substitute for a release. When you are ready to ship, cut a real tag — see [Cutting a release](/operations/deployment/helm-docker-versioning-and-ci/cutting-a-release.md). ## Notes vs annotated tags A note and an [annotated tag](/operations/deployment/helm-docker-versioning-and-ci/cutting-a-release.md) both put words on a version page, but they are not the same thing: | | Annotated tag | `.marked` note | | ---------- | ----------------------------------- | ------------------------------------- | | Lives in | the **source repo**, in git history | the **versions** repo | | Applies to | a release (`N.N.N`) only | any build — develop, RC or release | | Renders as | a **Release notes** section | a `> **Note**` line under the heading | | Written | at tag time | any time, afterwards | The practical difference: a tag annotation travels with the repo. Clone the service repo a year from now, run `git show 1.3.0`, and the notes are there — no dependency on the catalogue. A note is easier to add and to revise, and works on builds that were never released. Marking is the low-friction default: use it freely. Reach for an annotated tag when a release's notes should be embedded in the repository itself, which is worth doing for anything shipped to a deployment. ## Choosing what to write The note is free text, so it can carry whatever is useful. Some patterns that work well: * `**Intermediate Stable Version** — verified on staging` * `Passed the full QA cycle; safe for pilot deployments` * `` Known good with `registry-platform 0.0.0-develop.383` `` * `Use this one — **0.0.0-develop.206 has a broken migration**` Keep it short enough to read in a table cell. If it needs more explanation than that, the explanation probably belongs in a ticket, and the note should link to it. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.openg2p.org/operations/deployment/helm-docker-versioning-and-ci/marking-a-known-good-build.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.