docs: detailed step-by-step release branch setup guide#139
docs: detailed step-by-step release branch setup guide#139
Conversation
WalkthroughSwitches release workflow from per-release Konflux components to a perpetual release-branch staging model, documents step-by-step branch setup, GitLab mirror regex, Konflux/Tekton build behavior for Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant GH as GitHub
participant GL as GitLab (mirror)
participant KF as Konflux
participant TK as Tekton
participant QR as qontract-reconcile
participant CL as Cluster (deploy)
GH->>GL: Push to `release/*` (mirror sync)
GL->>KF: Mirror push triggers Konflux build
KF->>TK: Start Tekton pipeline (CEL matches `release/`)
TK-->>KF: Build image / produce artifact
KF->>QR: Create/merge MR with pinned `saas.yml` ref (SHA)
QR->>CL: Reconcile and deploy staged release
Note over QR,CL: Auto-merge `/lgtm` and SHA-based deploy flow
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
docs/RELEASE_BRANCHES.md (4)
119-126: Minor: specify language for the fenced code block.The linter suggests specifying a language for the code block. Since this is a flow diagram rather than actual code, you could use
```textto satisfy the linter while keeping the formatting intent clear.📝 Proposed fix
-``` +```text release branch commit (GitHub) → GitLab mirror syncs (regex: main|release\/.*) → Konflux (okp-mcp-rel component) builds image🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` around lines 119 - 126, The fenced block used for the flow diagram should declare a language to satisfy the linter; update the opening fence from ``` to ```text (and leave the closing fence as ```), i.e., edit the fenced code block in the RELEASE_BRANCHES.md content (the block starting with the three backticks that contains "release branch commit (GitHub)" and the arrow lines) so it becomes ```text to indicate plain text formatting.
98-99: Step 6 could use a bit more flesh on the bones.While the other steps give detailed UI walkthroughs, this one just waves vaguely at "update
IMAGE_TAGandIMAGE" without showing the actual format. A brief example snippet would help—especially since you're already documenting the quay repo difference.Something like:
IMAGE: quay.io/redhat-user-workloads/rhel-lightspeed-tenant/okp-mcp-rel IMAGE_TAG: <commit-sha-from-step-5>Entirely optional since presumably everyone doing this already knows the app-interface format, but consistency with the detailed approach elsewhere would be nice.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` around lines 98 - 99, Step 6 lacks a concrete example of how to set IMAGE and IMAGE_TAG in the app-interface update; update the docs to show the expected YAML keys and value formats by adding an example snippet demonstrating the quay repo and tag format (reference the `data/services/insights/rhel-lightspeed/cicd/saas.yml` variables `IMAGE` and `IMAGE_TAG`), e.g. illustrate `IMAGE` pointing to the release quay repo and `IMAGE_TAG` using the commit-sha from Step 5 so readers can copy the exact form when editing app-interface.
108-108: Consider removing the specific PR number reference."These were added to
mainin PR#136" is helpful context now, but documentation tends to outlive the relevance of specific PR numbers. In six months, nobody will care which PR it was—they'll just want to know the feature exists. Maybe rephrase as "These were added tomainand exist on all release branches created after that change."Not critical—just a general principle that documentation should age gracefully like fine wine, not milk.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` at line 108, Replace the sentence referencing "PR `#136`" with a more future-proof phrasing: locate the line mentioning `.tekton/push.yaml` and `.tekton/pull_request.yaml` and change "These were added to `main` in PR `#136` and exist on all release branches created after that." to something like "These were added to `main` and exist on all release branches created after that change." — remove the specific PR number while keeping `main` and the two .tekton files as the referenced artifacts.
59-59: Minor grammar: compound adjective needs a hyphen."First time setup" should be "First-time setup" when it precedes and modifies the noun it describes. English is weird like that—it's not a bug, it's a feature no one asked for.
📝 Proposed fix
-**First time setup (already done):** +**First-time setup (already done):**🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` at line 59, Replace the phrase "First time setup (already done):" with the hyphenated compound "First-time setup (already done):" so the adjective correctly modifies the noun; locate the exact heading line containing "First time setup (already done):" in docs/RELEASE_BRANCHES.md and update it to "First-time setup (already done):".
🤖 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/RELEASE_BRANCHES.md`:
- Around line 119-126: The fenced block used for the flow diagram should declare
a language to satisfy the linter; update the opening fence from ``` to ```text
(and leave the closing fence as ```), i.e., edit the fenced code block in the
RELEASE_BRANCHES.md content (the block starting with the three backticks that
contains "release branch commit (GitHub)" and the arrow lines) so it becomes
```text to indicate plain text formatting.
- Around line 98-99: Step 6 lacks a concrete example of how to set IMAGE and
IMAGE_TAG in the app-interface update; update the docs to show the expected YAML
keys and value formats by adding an example snippet demonstrating the quay repo
and tag format (reference the
`data/services/insights/rhel-lightspeed/cicd/saas.yml` variables `IMAGE` and
`IMAGE_TAG`), e.g. illustrate `IMAGE` pointing to the release quay repo and
`IMAGE_TAG` using the commit-sha from Step 5 so readers can copy the exact form
when editing app-interface.
- Line 108: Replace the sentence referencing "PR `#136`" with a more future-proof
phrasing: locate the line mentioning `.tekton/push.yaml` and
`.tekton/pull_request.yaml` and change "These were added to `main` in PR `#136`
and exist on all release branches created after that." to something like "These
were added to `main` and exist on all release branches created after that
change." — remove the specific PR number while keeping `main` and the two
.tekton files as the referenced artifacts.
- Line 59: Replace the phrase "First time setup (already done):" with the
hyphenated compound "First-time setup (already done):" so the adjective
correctly modifies the noun; locate the exact heading line containing "First
time setup (already done):" in docs/RELEASE_BRANCHES.md and update it to
"First-time setup (already done):".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 30993638-070b-4a01-8968-51cd95af81a5
📒 Files selected for processing (1)
docs/RELEASE_BRANCHES.md
Lifto
force-pushed
the
docs/update-release-branch-guide
branch
from
ccaf342 to
8692b99
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/RELEASE_BRANCHES.md (2)
66-71: Replace workstation-specific paths with neutral commands/placeholders.Using
~/Documents/Development/...bakes in one person’s filesystem. Prefer repo-agnostic examples so nobody has to debug your home directory from Line 66 onward.♻️ Suggested doc tweak
- cd ~/Documents/Development/okp-mcp + cd /path/to/okp-mcp - cd ~/Documents/Development/lscore-deploy + cd /path/to/lscore-deployOr use environment variables once, then reuse:
OKP_MCP_REPO=/path/to/okp-mcp LSCORE_DEPLOY_REPO=/path/to/lscore-deployAlso applies to: 77-80
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` around lines 66 - 71, The doc examples hard-code a user-specific path (~/Documents/Development/okp-mcp and ~/Documents/Development/lscore-deploy) for running git rev-parse; update the snippets to use repository-agnostic placeholders or environment variables instead (e.g., OKP_MCP_REPO and LSCORE_DEPLOY_REPO) and show the commands referencing those placeholders for both the okp-mcp and lscore-deploy examples (the lines containing "git rev-parse release/YYYY-MM-DD" and the preceding cd commands), and apply the same replacement to the later block around lines 77-80 so the docs no longer assume a specific home directory.
28-31: Add a quick verification step for the “already protected” ruleset claim.Runbooks age like milk when assumptions drift. Add one bullet to verify the
release/**ruleset exists before proceeding, so setup doesn’t silently skip protection.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/RELEASE_BRANCHES.md` around lines 28 - 31, Update the "2. GitHub branch protection" section to add a verification step that confirms the GitHub ruleset for the branch pattern `release/**` actually exists and matches the protections applied to `main`; instruct the operator to check via the GitHub repository settings or the GitHub REST/CLI (e.g., query the repository's rulesets) and to halt or report if the `release/**` ruleset is missing or differs from `main`.
🤖 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/RELEASE_BRANCHES.md`:
- Around line 95-106: The fenced code block in RELEASE_BRANCHES.md (the
unlabeled triple-backtick block that starts at the "release branch commit
(GitHub)" line) must include a language identifier to satisfy markdownlint
MD040; update the opening fence from ``` to ```text (or another appropriate
language) so the block becomes a labeled fenced code block and linting passes
while preserving the block contents and indentation.
---
Nitpick comments:
In `@docs/RELEASE_BRANCHES.md`:
- Around line 66-71: The doc examples hard-code a user-specific path
(~/Documents/Development/okp-mcp and ~/Documents/Development/lscore-deploy) for
running git rev-parse; update the snippets to use repository-agnostic
placeholders or environment variables instead (e.g., OKP_MCP_REPO and
LSCORE_DEPLOY_REPO) and show the commands referencing those placeholders for
both the okp-mcp and lscore-deploy examples (the lines containing "git rev-parse
release/YYYY-MM-DD" and the preceding cd commands), and apply the same
replacement to the later block around lines 77-80 so the docs no longer assume a
specific home directory.
- Around line 28-31: Update the "2. GitHub branch protection" section to add a
verification step that confirms the GitHub ruleset for the branch pattern
`release/**` actually exists and matches the protections applied to `main`;
instruct the operator to check via the GitHub repository settings or the GitHub
REST/CLI (e.g., query the repository's rulesets) and to halt or report if the
`release/**` ruleset is missing or differs from `main`.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 1e678036-7b84-40b6-a313-d6b1d37d0633
📒 Files selected for processing (1)
docs/RELEASE_BRANCHES.md
| ``` | ||
| release branch commit | ||
| → Konflux (okp-mcp-release component) builds image | ||
| → image tagged with commit SHA in quay.io | ||
| → update app-interface saas.yml IMAGE_TAG with that SHA | ||
| release branch commit (GitHub) | ||
| → GitLab mirror syncs (regex: main|release\/.*) | ||
| → Konflux builds image (okp-mcp component, .tekton/push.yaml CEL match) | ||
| → image tagged with commit SHA at quay.io/.../okp-mcp:<sha> | ||
| → update app-interface saas.yml: | ||
| - ref: <commit-sha> (for okp-mcp, lightspeed-stack, redhat-okp) | ||
| - IMAGE_TAG removed for okp-mcp (auto-derived from ref) | ||
| → /lgtm on the MR → App SRE bot auto-merges | ||
| → qontract-reconcile deploys to staging | ||
| → verify: oc get pods -n rhel-lightspeed-stage | ||
| ``` |
There was a problem hiding this comment.
Specify a language for the fenced block (markdownlint MD040).
Line 95 uses an unlabeled fence. Give it a language (for example text) to satisfy lint and keep tooling happy.
🧹 Minimal fix
-```
+```text
release branch commit (GitHub)
→ GitLab mirror syncs (regex: main|release\/.*)
→ Konflux builds image (okp-mcp component, .tekton/push.yaml CEL match)
@@
→ verify: oc get pods -n rhel-lightspeed-stage</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 95-95: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/RELEASE_BRANCHES.md` around lines 95 - 106, The fenced code block in
RELEASE_BRANCHES.md (the unlabeled triple-backtick block that starts at the
"release branch commit (GitHub)" line) must include a language identifier to
satisfy markdownlint MD040; update the opening fence from ``` to ```text (or
another appropriate language) so the block becomes a labeled fenced code block
and linting passes while preserving the block contents and indentation.
| ## Branch Protection | ||
| 1. Set `ref` to the **commit SHA** from each release branch HEAD: | ||
| - `okp-mcp-stage`: SHA from okp-mcp `release/YYYY-MM-DD` | ||
| - `lightspeed-stack-stage`: SHA from lscore-deploy `release/YYYY-MM-DD` |
There was a problem hiding this comment.
This part is a little confusing. Are we tying together image tags AND openshift templates together as a single SHA? I think we could leave the refs in app-interface set to main and just adjust image tags. That's what we did in rlsapi.
| → update app-interface saas.yml IMAGE_TAG with that SHA | ||
| release branch commit (GitHub) | ||
| → GitLab mirror syncs (regex: main|release\/.*) | ||
| → Konflux builds image (okp-mcp component, .tekton/push.yaml CEL match) |
There was a problem hiding this comment.
We will need to do the enterprise contract stuff here soon in konflux, so that's something to keep in mind. It just adds another step into the mix.
| → Konflux builds image (okp-mcp component, .tekton/push.yaml CEL match) | ||
| → image tagged with commit SHA at quay.io/.../okp-mcp:<sha> | ||
| → update app-interface saas.yml: | ||
| - ref: <commit-sha> (for okp-mcp, lightspeed-stack, redhat-okp) |
There was a problem hiding this comment.
Again, this is where stuff gets weird if we're doing releases on image tags AND openshift templates.
2 participants
Summary
docs/RELEASE_BRANCHES.mdwith full step-by-step instructions based on our actual setup experience