feat: auto-merge chart release and support release-v* hotfixes

[bhaveshpatel640]

Summary

Automate the post-npm chart path (wait for CI → squash-merge chart bot PR → OCI) and enable release-v* hotfix branches so patches do not have to ship from tip of main.

Chart SemVer is line-local: each RC cycle / stable X.Y line advances on its own. Hotfixes stay on that line instead of jumping to whatever main is publishing.

Closes AGE-2276

Diff

Before: Version Packages → npm → chart bot PR → human merge → chart OCI
After: Version Packages → npm + image → chart bot PR → auto-merge after CI → chart OCI

Hotfix: cut release-v* from a shipped SHA / charts/trueforge@* → cherry-pick + changeset → same Release lane on that branch (chart PR base = the release branch). Then pin control plane with helm-charts trueforge_chart_version=<chart SemVer> (helm-charts#6407).

Chart SemVer examples

Case	Starting point	Next chart
Normal RC on main	0.2.0-rc.14	0.2.0-rc.15
Hotfix mid-RC (stale cut)	Chart.yaml 0.2.0-rc.3, tags already at 0.2.0-rc.10	0.2.0-rc.11 (same RC line)
Mid-RC cut after same-core stable exists	Chart.yaml still 0.2.0-rc.*, tag 0.2.0 already published	Floor on 0.2.0 → 0.2.1 (does not retag 0.2.0)
Exit RC → stable	0.2.0-rc.14 + stable app	0.2.0
Hotfix older stable	Cut from 0.2.0; main on 0.3.0-rc.*	0.2.1 (not 0.3.0-rc.*)

Admin prerequisite (Pending)

Limited ruleset bypass for trueforge-dev-bot only (app id 4591571). No admin PAT. Required for auto-merge; without it the bot PR opens but squash-merge is blocked.

• Bypass mode pull_request — merge via PR only; no direct push
• Split rulesets — bot bypasses approvals; required check check on a no-bypass ruleset
• Same on org release-branch-protection (release-v*)

Changes

• release.yml also runs on release-v*; passes merge_chart_pr: true into the chart workflow
• build-and-prepare-chart-release.yml:
  • Chart PR base is main or the current release-v*
  • Separate bot heads: release-chart/trueforge vs release-chart/trueforge-<release-v*>
  • Optional auto-merge after CI (merge_chart_pr; default true from Release / false on manual dispatch)
  • Chart version baseline = max(Chart.yaml, highest tag on the same SemVer line) via scripts/highest-chart-tag-on-line.sh (RC line includes same-core stable)
  • Global serialize on open/merge (queue: max); wait for charts/trueforge@* tag before the next run
• release-chart.yml: publish on chart-bot PR merges into main or release-v*
• RELEASING.md: automated OCI lane, hotfix branch flow, line-local SemVer, limited bot bypass
• pnpm test:chart-version: covers resolve + line-local tag picker

How was this tested?

• Workflow YAML reviewed against recent chart PR CI timings (checks appear ~6–10s; initial sleep 20 before gh pr checks --watch)
• pnpm test:chart-version (resolve-chart-version + highest-chart-tag-on-line)
• No app/runtime code changes; full pnpm suite not required for this workflow/docs-only PR

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, python/trueforge_sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — fork PRs omit SDK regen; maintainers regenerate after merge
• Docs / .env.example updated if configuration or behavior changed

---

Note

Medium Risk
Changes release automation (bot squash-merge, branch rules, tag baseline) and expands npm/PyPI/chart triggers to release-v*; misconfiguration of bot ruleset bypass or SemVer logic could block or mis-tag releases.

Overview
Automates the post-npm chart path: after opening the chart bot PR, the workflow can wait for CI, squash-merge, and block until charts/trueforge@* exists (new merge_chart_pr input; Release passes true, manual dispatch defaults to false).

Release and chart publish now run on release-v* hotfix branches, not only main. Chart bot PRs target main or the hotfix branch, with separate heads (release-chart/trueforge vs release-chart/trueforge-<release-v*>) so parallel lanes do not clobber each other. release-chart.yml accepts merges of those bot branches into main or release-v*.

Chart SemVer bumping floors on max(Chart.yaml, highest published tag on the same line) via new scripts/highest-chart-tag-on-line.sh (RC lines include same-core stable; stable X.Y.* hotfixes ignore newer majors/RCs). Chart open/merge is globally serialized (queue: max); workflow concurrency is scoped per ref.

Docs and pnpm test:chart-version updated for the hotfix flow and line-local versioning.

^{Reviewed by Cursor Bugbot for commit 91c1b90. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 91c1b90

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[bhaveshpatel640]

Dependant PR: https://github.com/truefoundry/helm-charts/pull/6407

---

Today, after npm publishes, someone still has to manually merge the chart bot PR before the Helm chart hits OCI. This PR finishes that path automatically, and adds hotfix branches so you can patch an old line without taking everything on tip of main.

---

Normal release (main)

1. Merge Version Packages. npm and PyPI publish.
2. Image builds with that app version.
3. Bot opens or updates the chart PR (release-chart/trueforge to main).
4. Workflow waits for CI, squash-merges, then release-chart.yml tags and pushes OCI.

No human merge of the chart PR once the bot ruleset bypass exists.

---

Hotfix (release-v*)

1. Cut release-vX.Y.Z from a shipped SHA or charts/trueforge@* (not tip of main).
2. Cherry-pick the fix and a changeset.
3. The same Release lane runs on that branch.
4. Chart bot PR targets that branch (release-chart/trueforge-release-v…).
5. Same auto-merge to OCI.
6. Pin the control plane with helm-charts trueforge_chart_version=<that chart SemVer>.

---

Chart SemVer is line-local. Each line advances on its own.

Situation	Next chart
Normal RC	0.2.0-rc.14 becomes 0.2.0-rc.15
Stale mid-RC cut	Chart.yaml 0.2.0-rc.3, tags already 0.2.0-rc.10 becomes 0.2.0-rc.11
Mid-RC after stable exists	Chart.yaml still 0.2.0-rc.*, tag 0.2.0 exists, floor on 0.2.0 becomes 0.2.1
Exit RC	0.2.0-rc.14 plus a stable app becomes 0.2.0
Old stable hotfix	Cut from 0.2.0 while main is on 0.3.0-rc.* becomes 0.2.1

---

Release order

1. Once per cycle: pnpm changeset pre enter rc, commit .changeset/pre.json, merge to main.
2. All week: merge feature PRs to main (each with a changeset).
3. Release day: merge the Version Packages PR (x.y.z-rc.N).
4. Wait for Release: npm/PyPI, image, chart bot PR, auto-merge, OCI.
5. Note the chart SemVer (for example 0.2.0-rc.15).
6. Pin helm-charts with trueforge_chart_version=<chart SemVer> via the Release start UI or:

gh workflow run release-start.yml \
  -f kind=hotfix -f repositories='[]' -f chart_only=true \
  -f trueforge_chart_version=<chart-semver>

7. When the cycle ends: pnpm changeset pre exit, commit deletion of .changeset/pre.json, merge to main. This does not publish.
8. Merge Version Packages (stable x.y.z).
9. Wait for Release (npm latest, chart x.y.z, OCI).
10. Pin helm-charts with the stable chart SemVer (same as step 6).

---

Off-cycle hotfix only

git fetch origin
git checkout -b release-vX.Y.Z <shipped-sha>   # or charts/trueforge@A.B.C
git push -u origin release-vX.Y.Z
# cherry-pick fix + changeset → Version Packages on release-v* → Release → pin helm-charts

The chart stays on that line (0.2.1 while main is on 0.3.0-rc.*).

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 91c1b90. Configure here.}

[cursor]

Stable floor ignores later patch tags

Medium Severity

When Chart.yaml is still an RC, seeing the same-core stable tag makes highest-chart-tag-on-line.sh print that stable version and exit, so later X.Y.* tags are never considered. resolve-chart-version.sh then bumps only one step from that floor, so a stale cut (npm SHAs keep RC Chart.yaml because the chart bump lands on a later bot commit) can reuse an already-published tag and release-chart.yml refuses to move it.

Additional Locations (1)

• .github/workflows/build-and-prepare-chart-release.yml#L209-L215

 

^{Reviewed by Cursor Bugbot for commit 91c1b90. Configure here.}