HYPERFLEET-1268 - docs: add Konflux operations and release runbook#167
HYPERFLEET-1268 - docs: add Konflux operations and release runbook#167ciaranRoche wants to merge 1 commit into
Conversation
|
[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 |
📝 WalkthroughSummary by CodeRabbit
WalkthroughSix new markdown files are added under Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 11✅ Passed checks (11 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/docs/release/operations/configuration-map.md`:
- Line 66: The tag matcher regex pattern `v[0-9]+.[0-9]+.[0-9]+(-rc[0-9]+)?`
contains unescaped dots which act as wildcards matching any character instead of
literal dots. Update this regex pattern to escape the dots with backslashes
(change each `.` to `\.`) so that only valid semver-like tags trigger the
release, preventing malformed tags from matching and firing the release trigger
unintentionally.
- Around line 65-68: The version variable naming is inconsistent between this
configuration map documentation and the konflux-release-pipeline-design.md
document. Update all references to APP_VERSION in the table rows (specifically
in the descriptions of `.tekton/hyperfleet-<svc>-push.yaml`,
`.tekton/hyperfleet-<svc>-tag.yaml`, and the Dockerfile contract row) to use
VERSION instead, and update the Dockerfile contract description to reference ARG
VERSION and LABEL version, to match the documented pipeline behavior in
konflux-release-pipeline-design.md lines 270-296.
In `@hyperfleet/docs/release/operations/notifications.md`:
- Around line 11-23: The introductory sentence states that the HyperFleet
release pipeline emits signals to four places, but the table "Where to watch a
release" lists five surfaces: Slack, Konflux UI, Pyxis, GitHub commit status,
and Prow dashboard. Update the introductory sentence to change "four places" to
"five places" to match the number of entries in the table and resolve the
internal inconsistency.
In `@hyperfleet/docs/release/operations/pipeline-anatomy.md`:
- Around line 143-145: The grep pattern in the tag verification snippet uses
only a start-of-line anchor (^) but is missing an end-of-line anchor, which
causes it to match unintended tags like 0.3.0-rc10 and 0.3.0-rc11 in addition to
0.3.0-rc1. Add a dollar sign ($) at the end of the grep pattern to anchor it to
the end of the line, changing grep '^0.3.0-rc1' to grep '^0.3.0-rc1$' to ensure
an exact match of the intended tag.
In `@hyperfleet/docs/release/operations/release-runbook.md`:
- Around line 152-155: The git push command in the release tag step uses the
--tags flag which pushes all local tags rather than just the specified
release-1.5 tag, potentially leaking unrelated refs to remote. Replace the
single command that uses git push origin release-1.5 --tags with two separate
push commands: one to push the release-1.5 branch explicitly using git push
origin release-1.5, and another to push only the specific release-1.5 tag using
git push origin tag release-1.5 to ensure only the intended tag is uploaded to
remote.
🪄 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: Central YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 504a5ff5-8405-493c-8082-b9709d26788f
📒 Files selected for processing (7)
hyperfleet/docs/release/README.mdhyperfleet/docs/release/operations/configuration-map.mdhyperfleet/docs/release/operations/debugging.mdhyperfleet/docs/release/operations/notifications.mdhyperfleet/docs/release/operations/pipeline-anatomy.mdhyperfleet/docs/release/operations/release-runbook.mdhyperfleet/docs/release/operations/support.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift-hyperfleet/architecture(manual)openshift-hyperfleet/hyperfleet-api(manual)openshift-hyperfleet/hyperfleet-sentinel(manual)openshift-hyperfleet/hyperfleet-adapter(manual)openshift-hyperfleet/hyperfleet-broker(manual)
ciaranRoche
force-pushed
the
HYPERFLEET-1268-konflux-ops-docs
branch
4 times, most recently
from
9dd7e1f to
e0a4aee
Compare
Adds six engineer-facing operations docs under hyperfleet/docs/release/operations/ to complement the existing design and process docs: - configuration-map.md: every config file across konflux-release-data, the component repos, hyperfleet-release, and openshift/release - pipeline-anatomy.md: build vs release run, DAG, version flow, UI reading guide, skopeo confirmation - debugging.md: failure-mode runbook organised by symptom - notifications.md: #hyperfleet-e2e-status, webhook rotation, Pyxis, GitHub PR checks, Prow signals - release-runbook.md: copy-paste commands for RC -> GA, fix cycle, and hotfix - support.md: Slack channels (#forum-conforma, not the renamed #forum-konflux-contract), JIRA queues, escalation contacts README index updated with an Operations section linking the new docs. Per-repo RELEASING.md stubs (hyperfleet-api, -sentinel, -adapter, -release) will follow in separate PRs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ciaranRoche
force-pushed
the
HYPERFLEET-1268-konflux-ops-docs
branch
from
e0a4aee to
080abd8
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/docs/release/operations/release-runbook.md`:
- Around line 153-155: The unqualified refspec in the git push command for
release-1.5 branch is ambiguous and will fail when a tag with the same name
exists. Replace the ambiguous `git push origin release-1.5` command with a fully
qualified branch refspec using `git push origin refs/heads/release-1.5` to
explicitly specify that you are pushing the branch rather than the tag,
eliminating the refspec ambiguity and ensuring deterministic release automation.
🪄 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: Central YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: c4b6cfc2-595d-4a41-a8ba-80ef8ccc3e01
📒 Files selected for processing (7)
hyperfleet/docs/release/README.mdhyperfleet/docs/release/operations/configuration-map.mdhyperfleet/docs/release/operations/debugging.mdhyperfleet/docs/release/operations/notifications.mdhyperfleet/docs/release/operations/pipeline-anatomy.mdhyperfleet/docs/release/operations/release-runbook.mdhyperfleet/docs/release/operations/support.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift-hyperfleet/architecture(manual)openshift-hyperfleet/hyperfleet-api(manual)openshift-hyperfleet/hyperfleet-sentinel(manual)openshift-hyperfleet/hyperfleet-adapter(manual)openshift-hyperfleet/hyperfleet-broker(manual)
✅ Files skipped from review due to trivial changes (5)
- hyperfleet/docs/release/operations/debugging.md
- hyperfleet/docs/release/operations/configuration-map.md
- hyperfleet/docs/release/operations/pipeline-anatomy.md
- hyperfleet/docs/release/README.md
- hyperfleet/docs/release/operations/support.md
🚧 Files skipped from review as they are similar to previous changes (1)
- hyperfleet/docs/release/operations/notifications.md
| git tag release-1.5 | ||
| git push origin release-1.5 # push the branch | ||
| git push origin tag release-1.5 # push the tag explicitly (same name as branch) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the file exists and read the context around lines 153-155
if [ -f "hyperfleet/docs/release/operations/release-runbook.md" ]; then
echo "=== File exists, reading lines 145-165 ==="
sed -n '145,165p' hyperfleet/docs/release/operations/release-runbook.md
echo ""
echo "=== Total file line count ==="
wc -l hyperfleet/docs/release/operations/release-runbook.md
else
echo "File not found at hyperfleet/docs/release/operations/release-runbook.md"
echo "Searching for similar file patterns..."
find . -name "*release-runbook*" -o -name "*release*operations*"
fiRepository: openshift-hyperfleet/architecture
Length of output: 767
🌐 Web query:
Git ambiguous refspec behavior when tag and branch have same name - git-push documentation
💡 Result:
When a branch and a tag share the same name in a Git repository, Git's command-line tools often encounter ambiguity [1][2]. This is because Git uses unqualified names (shorthand) to resolve references, and if both refs/heads/<name> (branch) and refs/tags/<name> (tag) exist, Git cannot determine which one you intend to use [3][2]. When using git push, this ambiguity frequently results in an error message such as "error: src refspec matches more than one" or "error: dst refspec matches more than one" [4][3][1]. Git refuses to proceed because it cannot safely resolve the ambiguous refspec [1]. To resolve this issue, you must use fully qualified refnames in your git push command [3][5][2]. By explicitly specifying the namespace (e.g., refs/heads/ or refs/tags/), you remove the ambiguity [3][6]. Common commands to resolve the push: To push a branch specifically: git push origin refs/heads/:refs/heads/ [4] To push a tag specifically: git push origin refs/tags/:refs/tags/ [4][6] If the ambiguity is causing problems in other workflows (like checkout or merge), you can also delete the offending tag or branch to resolve the conflict [4][1][2]: To delete a local tag: git tag -d [4][1] To delete a remote tag safely (without accidentally deleting a branch): git push origin:refs/tags/ [6] It is a recommended best practice to avoid using identical names for tags and branches to prevent these ambiguities and potential operational errors [1][5].
Citations:
- 1: https://dev.to/andreasbergstrom/error-src-refspec-refsheadsfoo-matches-more-than-one-4ho0
- 2: https://deverrors.com/errors/git-refname-is-ambiguous
- 3: https://stackoverflow.com/questions/70584317/git-push-error-dst-refspec-refs-heads-main-matches-more-than-one
- 4: https://stackoverflow.com/questions/9378760/git-push-local-branch-with-same-name-as-remote-tag
- 5: https://stackoverflow.com/questions/28192422/git-warning-refname-xxx-is-ambiguous
- 6: https://support.atlassian.com/bitbucket-cloud/kb/removing-a-tag-when-having-a-branch-with-the-same-name/
Specify branch and tag refspecs explicitly in push commands.
Line 154 uses unqualified git push origin release-1.5 which is ambiguous when a tag with the same name exists (line 153). Git documents that ambiguous refspecs produce "error: src refspec matches more than one" and fail the push. This breaks release automation determinism. Use fully qualified refs to eliminate ambiguity:
Fix
git tag release-1.5
-git push origin release-1.5 # push the branch
-git push origin tag release-1.5 # push the tag explicitly (same name as branch)
+git push origin refs/heads/release-1.5 # push the branch explicitly
+git push origin refs/tags/release-1.5 # push the tag explicitly🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hyperfleet/docs/release/operations/release-runbook.md` around lines 153 -
155, The unqualified refspec in the git push command for release-1.5 branch is
ambiguous and will fail when a tag with the same name exists. Replace the
ambiguous `git push origin release-1.5` command with a fully qualified branch
refspec using `git push origin refs/heads/release-1.5` to explicitly specify
that you are pushing the branch rather than the tag, eliminating the refspec
ambiguity and ensuring deterministic release automation.
1 participant
Summary
Adds six engineer-facing operations docs under
hyperfleet/docs/release/operations/to complement the existing design (konflux-release-pipeline-design.md) and process (hyperfleet-release-process.md) docs. These are the docs an engineer reaches for during a release or when something fails.release-runbook.md— copy-paste command sequence for RC → GA, fix cycle, and hotfixpipeline-anatomy.md— reading a Konflux PipelineRun, the build-vs-release distinction, where to look in the UI, version flowdebugging.md— failure-mode runbook organised by symptom (no PipelineRun, build red, build green but image not in Quay, wrong version label, RC E2E didn't trigger, EC violation, …)configuration-map.md— every release-related config file across the six repos (konflux-release-data,hyperfleet-api,-sentinel,-adapter,hyperfleet-release,openshift/release)notifications.md—#hyperfleet-e2e-status, webhook secret rotation, Pyxis, GitHub PR checks, Prow status signalssupport.md— Slack channels, JIRA queues, Konflux UI, escalationhyperfleet/docs/release/README.mdindex updated with an Operations section linking the new docs.Closes HYPERFLEET-1268 (in part — per-repo
RELEASING.mdstubs follow in separate PRs).Test plan
markdownlint,yamllint,linkcheckgreenhyperfleet/docs/release/README.mdrelease-runbook.mdagainst the next planned RC and confirms it works without context-switching to other docsNotes for reviewers
#hyperfleet-e2e-status).hyperfleet-chartintentionally not covered — charts ship from per-component.tekton/*-chart-push.yamlpipelines, the chart repo is dev-time reference only.Follow-ups (separate PRs, after this merges):
RELEASING.mdstub at root ofhyperfleet-apiRELEASING.mdstub at root ofhyperfleet-sentinelRELEASING.mdstub at root ofhyperfleet-adapterRELEASING.mdstub at root ofhyperfleet-release