Add Konflux release process documentation#391
Conversation
|
Skipping CI for Draft Pull Request. |
openshift-ci
Bot
added
the
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
alebedev87
force-pushed
the
konflux-release-doc
branch
from
30b9552 to
2873801
Compare
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded docs/konflux-release.md with a step‑by‑step Konflux release procedure for the ExternalDNS Operator: prerequisites, required synchronized merges and VERSION alignment, nudging order (operand then operator), bundle image digest checks via 🚥 Pre-merge checks | ✅ 10✅ Passed checks (10 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
alebedev87
force-pushed
the
konflux-release-doc
branch
from
2873801 to
35716fe
Compare
openshift-ci
Bot
removed
the
do-not-merge/work-in-progress
|
|
||
| In order for the stage release pipeline to pass the Conforma test, the registry/repository in [`bundle-hack/container_digest.sh`](https://github.com/openshift/external-dns-operator/blob/main/bundle-hack/container_digest.sh) must be set to `registry.stage.redhat.io/edo/*`. Keep the digests the same as the ones created by the nudging PR. | ||
|
|
||
| This change of the registry to stage is currently not automated and must be done manually — create a PR with the registry update and merge it into the target branch. |
There was a problem hiding this comment.
Should we create a Jira to track this, something like: "TODO: Automate registry swap"?
That is if we want to automate this... 🤔
There was a problem hiding this comment.
That is if we want to automate this..
Not sure yet, maybe. The idea of this doc is to capture the current state. I would prefer the whole process to be automated (agentic release or something along those lines).
For the moment I changed the wording to not state of possible automation but just record the needed steps.
|
@coderabbitai have a review at this PR please |
|
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (7)
docs/konflux-release.md (7)
122-122: Consider using a placeholder for the version in the example.The example shows
'external-dns-operator.v1.2.1', which doesn't match the current VERSION file (1.3.3). While line 126 instructs users to replace this, consider using a more obvious placeholder like'external-dns-operator.v<VERSION>'or'external-dns-operator.vX.Y.Z'to make it clearer that this is a value to be substituted.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 122, Replace the literal example string 'external-dns-operator.v1.2.1' with a clear placeholder to indicate substitution by the current VERSION (e.g., 'external-dns-operator.v<VERSION>' or 'external-dns-operator.vX.Y.Z'); update the example line that contains the grep command so it references the placeholder instead of a hardcoded version and ensure the surrounding text still instructs users to replace that placeholder with the actual value from the VERSION file.
13-13: Clarify the primary branch naming.The phrase "
main/master" is ambiguous. If both repositories use the same branch naming convention, specify which one (e.g., "both repositories usemain"). If they differ, explicitly state which repository uses which branch name.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 13, Update the ambiguous branch wording in the sentence "Both repositories must be on the same branch: `main`/`master` for the latest development or `release-X.Y` for a specific release." to explicitly state which primary branch to use (e.g., "both repositories must use `main` for latest development") or, if they differ, specify per-repo (e.g., "repo-A uses `main`, repo-B uses `master`"); locate and modify the sentence in docs/konflux-release.md so it clearly names the exact branch names instead of the "main/master" shorthand.
73-73: Clarify "proxy registry" or provide reference.The term "proxy registry" is introduced without explanation. Consider briefly explaining what this refers to or providing a link to documentation that describes the proxy registry concept in the Konflux/OCP context.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 73, Clarify the term "proxy registry" where "index image" and "CatalogSource" are mentioned: add a short definition explaining it as the internal/offline registry used to mirror external images for air-gapped OCP clusters, and include a link to the Konflux/OCP documentation or Red Hat docs that describe registry mirroring and proxy registries; also add a one-line example or note pointing QE to the mirroring + CatalogSource workflow (referencing "index image" and "CatalogSource") so readers know where to find step-by-step instructions.
57-57: Clarify where the extracted bundle digest is used.The instruction states "take the bundle image digest from the snapshot — this is the digest needed for the next step," but the following section (Update FBC Catalogs with Stage Bundle) doesn't explicitly mention using this specific digest. Consider adding a forward reference or clarifying that this digest should be used in the
olm.bundleentry mentioned in line 64.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 57, Add a clarifying sentence after the step that extracts the bundle image digest stating that this exact digest must be used when updating the FBC Catalogs: specifically it should replace the image reference in the olm.bundle entry in the "Update FBC Catalogs with Stage Bundle" section; add a brief forward reference or parenthetical like "use this digest in the olm.bundle entry" so readers know where to paste the digest.
98-110: Add guidance for example Release CR values.The example Release CR contains specific hardcoded values (namespace, author
gpiotrow, snapshot nameext-dns-optr-fbc-v4-21-45gt6, etc.) that should be replaced by users. Consider either:
- Using placeholder syntax (e.g.,
<NAMESPACE>,<SNAPSHOT_NAME>,<AUTHOR>) with a note explaining what to replace, or- Adding a comment above the example clarifying that these values are examples and must be updated to match the actual snapshot and user context.
This will help prevent users from copying these values directly without understanding what needs to be customized.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` around lines 98 - 110, The example Release CR uses hardcoded fields (metadata.namespace, metadata.labels.release.appstudio.io/author, metadata.generateName, and spec.snapshot) that users must replace; update the YAML in the Release example to use clear placeholders like <NAMESPACE>, <AUTHOR>, <SNAPSHOT_NAME>, <GENERATE_NAME_PREFIX> (or add a brief comment above the block) and include a one-line note explaining these placeholders must be replaced with values matching the user's snapshot and context so readers don't copy the example verbatim.
1-126: Consider adding operational guidance.The documentation thoroughly covers the happy path but could benefit from brief guidance on:
- What to do if a release pipeline fails at various stages
- Rollback procedures if issues are discovered after production release
- Troubleshooting common pipeline failures beyond Conforma violations
This would make the documentation more actionable for operators dealing with real-world scenarios.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` around lines 1 - 126, Add an "Operational Guidance" section to the release doc that complements the existing happy-path steps (e.g., Verify Conforma, Release to Stage Registry, Update FBC Catalogs with Stage Bundle) and the bundle-hack/container_digest.sh references: briefly describe actions to take when a release pipeline fails at each major stage (stage push, Conforma, FBC update, production push), include rollback procedures for operator/operand/bundle (how to revert container_digest.sh changes and restore previous snapshots/releases), and add a short troubleshooting checklist for common pipeline failures (Conforma violations, image digest mismatches, nudging/PR issues) plus pointers to make generate-catalog and Konflux console actions for recovery.
85-88: Consider reducing repetition.Lines 85 and 88 both emphasize that the digest remains the same. This could be consolidated to reduce redundancy while maintaining clarity.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` around lines 85 - 88, Consolidate the duplicate note about the image digest by removing the repeated sentence and adding a single clear statement once (for example after step 1 or as a parenthetical in the introduction) that the digest remains the same as the stage bundle and that changing the digest requires re-running the testing process; update the instructions that reference catalog/v4.XX/catalog-template.yaml, the stage registry bundle -> production bundle swap, and make generate-catalog so they all refer to this single digest-note instead of repeating it.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/konflux-release.md`:
- Line 122: Replace the literal example string 'external-dns-operator.v1.2.1'
with a clear placeholder to indicate substitution by the current VERSION (e.g.,
'external-dns-operator.v<VERSION>' or 'external-dns-operator.vX.Y.Z'); update
the example line that contains the grep command so it references the placeholder
instead of a hardcoded version and ensure the surrounding text still instructs
users to replace that placeholder with the actual value from the VERSION file.
- Line 13: Update the ambiguous branch wording in the sentence "Both
repositories must be on the same branch: `main`/`master` for the latest
development or `release-X.Y` for a specific release." to explicitly state which
primary branch to use (e.g., "both repositories must use `main` for latest
development") or, if they differ, specify per-repo (e.g., "repo-A uses `main`,
repo-B uses `master`"); locate and modify the sentence in
docs/konflux-release.md so it clearly names the exact branch names instead of
the "main/master" shorthand.
- Line 73: Clarify the term "proxy registry" where "index image" and
"CatalogSource" are mentioned: add a short definition explaining it as the
internal/offline registry used to mirror external images for air-gapped OCP
clusters, and include a link to the Konflux/OCP documentation or Red Hat docs
that describe registry mirroring and proxy registries; also add a one-line
example or note pointing QE to the mirroring + CatalogSource workflow
(referencing "index image" and "CatalogSource") so readers know where to find
step-by-step instructions.
- Line 57: Add a clarifying sentence after the step that extracts the bundle
image digest stating that this exact digest must be used when updating the FBC
Catalogs: specifically it should replace the image reference in the olm.bundle
entry in the "Update FBC Catalogs with Stage Bundle" section; add a brief
forward reference or parenthetical like "use this digest in the olm.bundle
entry" so readers know where to paste the digest.
- Around line 98-110: The example Release CR uses hardcoded fields
(metadata.namespace, metadata.labels.release.appstudio.io/author,
metadata.generateName, and spec.snapshot) that users must replace; update the
YAML in the Release example to use clear placeholders like <NAMESPACE>,
<AUTHOR>, <SNAPSHOT_NAME>, <GENERATE_NAME_PREFIX> (or add a brief comment above
the block) and include a one-line note explaining these placeholders must be
replaced with values matching the user's snapshot and context so readers don't
copy the example verbatim.
- Around line 1-126: Add an "Operational Guidance" section to the release doc
that complements the existing happy-path steps (e.g., Verify Conforma, Release
to Stage Registry, Update FBC Catalogs with Stage Bundle) and the
bundle-hack/container_digest.sh references: briefly describe actions to take
when a release pipeline fails at each major stage (stage push, Conforma, FBC
update, production push), include rollback procedures for
operator/operand/bundle (how to revert container_digest.sh changes and restore
previous snapshots/releases), and add a short troubleshooting checklist for
common pipeline failures (Conforma violations, image digest mismatches,
nudging/PR issues) plus pointers to make generate-catalog and Konflux console
actions for recovery.
- Around line 85-88: Consolidate the duplicate note about the image digest by
removing the repeated sentence and adding a single clear statement once (for
example after step 1 or as a parenthetical in the introduction) that the digest
remains the same as the stage bundle and that changing the digest requires
re-running the testing process; update the instructions that reference
catalog/v4.XX/catalog-template.yaml, the stage registry bundle -> production
bundle swap, and make generate-catalog so they all refer to this single
digest-note instead of repeating it.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 98c463b0-873a-49d4-8625-31bae3e3c5ae
📒 Files selected for processing (1)
docs/konflux-release.md
alebedev87
force-pushed
the
konflux-release-doc
branch
2 times, most recently
from
2a504ba to
ed6bd69
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/konflux-release.md (1)
15-15: Use branch-aware links instead ofblob/mainlinks.These links will always open
main, which can mismatch release-branch workflows and cause readers to validate the wrong file state.Proposed doc fix
-The merged code should include the version change in the [`VERSION`](https://github.com/openshift/external-dns-operator/blob/main/VERSION) file matching the target release version. +The merged code should include the version change in the [`VERSION`](../VERSION) file matching the target release version. -Verify that the latest images pushed by the component push pipelines are reflected in [`bundle-hack/container_digest.sh`](https://github.com/openshift/external-dns-operator/blob/main/bundle-hack/container_digest.sh). +Verify that the latest images pushed by the component push pipelines are reflected in [`bundle-hack/container_digest.sh`](../bundle-hack/container_digest.sh). -In order for the stage release pipeline to pass the Conforma test, the registry/repository in [`bundle-hack/container_digest.sh`](https://github.com/openshift/external-dns-operator/blob/main/bundle-hack/container_digest.sh) must be set to `registry.stage.redhat.io/edo/*`. +In order for the stage release pipeline to pass the Conforma test, the registry/repository in [`bundle-hack/container_digest.sh`](../bundle-hack/container_digest.sh) must be set to `registry.stage.redhat.io/edo/*`. -Update [`bundle-hack/container_digest.sh`](https://github.com/openshift/external-dns-operator/blob/main/bundle-hack/container_digest.sh) to use the production registry (`registry.redhat.io/edo/*`), keeping the same digests. +Update [`bundle-hack/container_digest.sh`](../bundle-hack/container_digest.sh) to use the production registry (`registry.redhat.io/edo/*`), keeping the same digests.Also applies to: 27-27, 53-53, 77-77
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 15, The docs currently use hard-coded blob/main GitHub URLs (e.g. https://github.com/openshift/external-dns-operator/blob/main/VERSION) which always open main; replace those hard-coded blob/main links in docs/konflux-release.md with branch-aware references—prefer relative repository links (e.g. ./VERSION) or interpolate the current release branch (e.g. /blob/${RELEASE_BRANCH}/VERSION) so the link resolves to the file on the active release branch; update every occurrence of the blob/main URL pattern in the file (including the other identical occurrences noted) to the branch-aware form.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/konflux-release.md`:
- Around line 132-140: Update the verification snippet to avoid hardcoded OCP
minors and bundle version by introducing environment-driven variables: add
RELEASE_VERSION (used in the grep pattern replacing
'external-dns-operator.v1.2.1') and SUPPORTED_OCP_MINORS (used in the for v in
${SUPPORTED_OCP_MINORS} loop replacing the fixed list 12..21), default both with
sensible examples, and change the grep to use
"external-dns-operator.v${RELEASE_VERSION}" so the loop and version check are
configurable per branch.
---
Nitpick comments:
In `@docs/konflux-release.md`:
- Line 15: The docs currently use hard-coded blob/main GitHub URLs (e.g.
https://github.com/openshift/external-dns-operator/blob/main/VERSION) which
always open main; replace those hard-coded blob/main links in
docs/konflux-release.md with branch-aware references—prefer relative repository
links (e.g. ./VERSION) or interpolate the current release branch (e.g.
/blob/${RELEASE_BRANCH}/VERSION) so the link resolves to the file on the active
release branch; update every occurrence of the blob/main URL pattern in the file
(including the other identical occurrences noted) to the branch-aware form.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: f239d0e5-f1e4-487e-8d73-73b1ac67ea98
📒 Files selected for processing (1)
docs/konflux-release.md
alebedev87
force-pushed
the
konflux-release-doc
branch
from
ed6bd69 to
39c377a
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/konflux-release.md (3)
79-79: Clarify the explanation of stage release failure.The statement "The automated release to stage will fail because the images contain unreleased images from the production registry" could be clearer. Consider rephrasing to: "The automated stage release will fail because the snapshot references images from the production registry that have not yet been released there."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 79, The sentence explaining why automated stage releases fail is unclear; update the sentence in the paragraph that currently reads "The automated release to stage will fail because the images contain unreleased images from the production registry" to the clearer phrasing "The automated stage release will fail because the snapshot references images from the production registry that have not yet been released there." Make this replacement in the same paragraph describing creating a Release CR or triggering a release from the Konflux console (the text mentioning "Release CR" and "Konflux console" identifies the location).
38-38: Clarify which branch triggers the release.The phrase "into an external-dns-operator branch" is vague. Consider specifying "into the target branch of the external-dns-operator repository" for clarity.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 38, The sentence "Each merge into an `external-dns-operator` branch triggers an automatic release..." is ambiguous about which branch triggers the release; update the sentence to explicitly state the target branch in the external-dns-operator repository (e.g., "Each merge into the target branch of the external-dns-operator repository triggers an automatic release to the stage registry") so readers know which branch is meant; edit the line in docs/konflux-release.md replacing the original phrase with the clarified wording and keep the rest of the sentence about the release pipeline and `verify-conforma` task unchanged.
47-47: Specify the location of release examples.The reference to "other release examples in the repository" is vague. Consider providing a specific path or directory, such as
docs/konflux-releases/or linking to specific example files.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/konflux-release.md` at line 47, The sentence referencing "other release examples in the repository" is vague; update the line that currently reads "Refer to the [Konflux documentation](https://konflux-ci.dev/docs/) and other release examples in the repository to resolve these violations." to point to a specific location or files by replacing "other release examples in the repository" with either a single directory name (e.g., docs/konflux-releases/) or explicit links to representative example files (replace the vague phrase with direct markdown links to the example release notes), so readers can immediately find the examples.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/konflux-release.md`:
- Line 79: The sentence explaining why automated stage releases fail is unclear;
update the sentence in the paragraph that currently reads "The automated release
to stage will fail because the images contain unreleased images from the
production registry" to the clearer phrasing "The automated stage release will
fail because the snapshot references images from the production registry that
have not yet been released there." Make this replacement in the same paragraph
describing creating a Release CR or triggering a release from the Konflux
console (the text mentioning "Release CR" and "Konflux console" identifies the
location).
- Line 38: The sentence "Each merge into an `external-dns-operator` branch
triggers an automatic release..." is ambiguous about which branch triggers the
release; update the sentence to explicitly state the target branch in the
external-dns-operator repository (e.g., "Each merge into the target branch of
the external-dns-operator repository triggers an automatic release to the stage
registry") so readers know which branch is meant; edit the line in
docs/konflux-release.md replacing the original phrase with the clarified wording
and keep the rest of the sentence about the release pipeline and
`verify-conforma` task unchanged.
- Line 47: The sentence referencing "other release examples in the repository"
is vague; update the line that currently reads "Refer to the [Konflux
documentation](https://konflux-ci.dev/docs/) and other release examples in the
repository to resolve these violations." to point to a specific location or
files by replacing "other release examples in the repository" with either a
single directory name (e.g., docs/konflux-releases/) or explicit links to
representative example files (replace the vague phrase with direct markdown
links to the example release notes), so readers can immediately find the
examples.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: dce465e9-e0bd-4eeb-bd54-3679db5c6784
📒 Files selected for processing (2)
docs/konflux-release.mddocs/konflux-releases/fbc-prod-releases-1.2.1.yaml
✅ Files skipped from review due to trivial changes (1)
- docs/konflux-releases/fbc-prod-releases-1.2.1.yaml
alebedev87
force-pushed
the
konflux-release-doc
branch
from
39c377a to
747eda0
Compare
alebedev87
force-pushed
the
konflux-release-doc
branch
from
747eda0 to
5f5aca0
Compare
alebedev87
force-pushed
the
konflux-release-doc
branch
from
5f5aca0 to
8ba42d8
Compare
There was a problem hiding this comment.
I think it's a good file to have as a reference, though I think we should use some imaginary snapshots as example and/or use the stage release plans just to avoid any accidental oc apply -f
There was a problem hiding this comment.
Fair point. I reshaped docs/konflux-releases/ directory into a release history "database" with markdown files for each release. Release CRs are now just yaml code blocks to prevent any accidental creation. Plus we have a small track record of what was released.
Add markdown files to record the release history with Jira links, release descriptions, and FBC production Release CRs.
alebedev87
force-pushed
the
konflux-release-doc
branch
from
8ba42d8 to
f3a5958
Compare
|
@alebedev87: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
3 participants
Skeleton for the release process on Konflux. Goal is to be simple and list the main steps.