ci: switch chart release flow to release-please (FB-1938) (#20)

simonzelenskifbio · claude · web-flow · commit 0d0fe7fab064 · 2026-07-06T13:38:32.000+02:00
**Background** FB-1938: The chart release flow auto-bumps `helm/Chart.yaml` `version` from the merge-commit subject in a homegrown bash step and pushes the bump back to `main`; we want release-please as the source of truth instead, matching `firebolt-kubernetes-operator` (FB-1671). **Summary** Switches chart versioning and changelog generation to [release-please](https://github.com/googleapis/release-please), adapted for this single-chart repo (no app image / cosign / CRDs chart). What changes: - `release-please-config.json` + `.release-please-manifest.json` — one `helm` package (`release-type: helm`), tags `v<version>`, changelog sections mirroring the operator. - `helm-release-cd.yaml` rewritten: a `release-please` job opens/updates the release PR; a `release-chart` job (gated on `release_created`) regenerates the README, packages the chart, and pushes it to GHCR. `appVersion` stays owned by the upstream image-release automation. - `pr-title.yaml` added — validates conventional-commit PR titles (release-please derives versions from squash-merge titles), skipping dependabot/release-please branches. - `helm-test.yaml` — skips the kind e2e on release-please branches (the release PR only bumps the version + changelog over templates that already passed on the feature PR). - `AGENTS.md` / `helm/AGENTS.md` updated to describe the flow. Going forward, releasing is a two-step flow: merge a `feat:`/`fix:`/`chore(deps):` PR, then merge the release PR release-please opens. Only `feat`/`fix`/`perf`/`revert`/`chore(deps)` cut a release; plain `chore:`/`refactor:`/`docs:` merges no longer publish a chart. Do not hand-bump `Chart.yaml` `version` — release-please owns it. Breaking changes bump minor while pre-1.0. **Bootstrap (required before this takes effect):** no git tags exist, so anchor release-please at the current release before merging, or its first run scans all history. Tags are bare SemVer (no `v`), matching the chart version and OCI tag: ``` git tag 0.2.0 <main-HEAD> && git push origin 0.2.0 ``` **Test Plan** - `release-please-config.json` / `.release-please-manifest.json` validated as JSON. - Workflows reviewed for actionlint/zizmor: all actions pinned to SHAs (reusing existing repo pins), no `${{ }}` expansions inside `run:` blocks. - Traced trigger behavior on the release PR and on merge: `docs-sync`/`docs-validate` no-op, `helm-validate` lints the bumped chart, `helm-test` now skipped on release-please branches, and the README sync commit carries `[skip ci]` so it does not re-trigger the release run. - End-to-end release behavior will be confirmed on the first real run after the `v0.2.0` bootstrap tag is pushed.  --- > [!NOTE] > **Medium Risk** > Changes how every chart version reaches production (tags, GHCR, changelog) and tightens which merges trigger releases; misconfiguration or missing bootstrap tag could affect the first release run. > > **Overview** > Replaces the **homegrown bash auto-bump** on `main` with **[release-please](https://github.com/googleapis/release-please)** as the sole owner of `helm/Chart.yaml` `version` and changelog. > > **Release pipeline:** `helm-release-cd` now runs a `release-please` job on every push to `main` (no longer limited to `helm/**` paths). It opens/updates a release PR from conventional commits; merging that PR tags bare SemVer, cuts a GitHub release, and only then runs **`release-chart`** to regenerate `helm/README.md` (with `[skip ci]`), package, and push OCI to GHCR. The old logic that inferred patch/minor/major from the latest merge commit and pushed version/changelog bumps directly to `main` is removed. > > **New config:** `release-please-config.json` and `.release-please-manifest.json` (anchored at `0.2.0`) define a single `helm` package with operator-aligned changelog sections; only certain commit types are releasable. > > **CI gates:** **`pr-title.yaml`** enforces conventional PR titles (with issue refs) because squash-merge titles feed release-please. **`helm-test`** skips `release-please/*` branches so version-only release PRs do not rerun the long kind e2e. > > **Docs:** `AGENTS.md` / `helm/AGENTS.md` describe the two-step release (feature PR → release PR) and that hand-bumping chart `version` is no longer allowed; `appVersion` stays on separate image automation. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 03941b6. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/.github/workflows/helm-release-cd.yaml b/.github/workflows/helm-release-cd.yaml
@@ -1,4 +1,12 @@
 ---
+# Chart versioning is driven by release-please: conventional-commit pushes to
+# main accumulate on an automated release PR (opened/updated by the release-please
+# job); merging that PR bumps helm/Chart.yaml `version`, prepends helm/CHANGELOG.md,
+# tags `<version>` (bare SemVer, matching the chart version and OCI tag), and cuts
+# a GitHub release. Only then does release-chart package
+# and push the OCI chart to GHCR. Chart `appVersion` is NOT managed here -- it is
+# bumped independently by the upstream image-release automation (a chore(deps):
+# commit, which release-please still counts as releasable).
 name: Helm - Release Chart
 
 env:
@@ -8,8 +16,6 @@ env:
 on:
   push:
     branches: [main]
-    paths:
-      - "helm/**"
   workflow_dispatch:
 
 permissions: {}
@@ -18,7 +24,44 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      # Single package at path `helm`, so release-please-action keys its outputs
+      # by that path (`helm--<name>`) rather than the un-prefixed root aliases.
+      release_created: ${{ steps.release.outputs['helm--release_created'] }}
+      tag_name: ${{ steps.release.outputs['helm--tag_name'] }}
+      version: ${{ steps.release.outputs['helm--version'] }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          show-progress: "false"
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          client-id: ${{ secrets.GH_APP_FB_DB_CI_WRITER_CLIENT_ID }}
+          private-key: ${{ secrets.GH_APP_FB_DB_CI_WRITER_APP_KEY_PEM }}
+          permission-contents: write
+          permission-pull-requests: write
+
+      - name: Release Please
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
   release-chart:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -28,7 +71,6 @@ jobs:
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           show-progress: "false"
-          fetch-depth: 2
           persist-credentials: false
 
       - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
@@ -49,65 +91,30 @@ jobs:
           sudo tar -xzf "${HELM_DOCS_ARCHIVE}" -C /usr/local/bin helm-docs
           rm -f "${HELM_DOCS_ARCHIVE}" checksums.txt
 
-      - name: Determine chart version
-        id: chart
+      - name: Sync generated chart README to released version
+        # release-please bumps Chart.yaml `version` on the release PR but does not
+        # run helm-docs, so the README version badge lags by one release. Regenerate
+        # and commit it back. helm/README.md is cosmetic (the chart's .helmignore
+        # excludes *.md, so it is never packaged). The commit carries `[skip ci]` so
+        # this direct push to main does not trigger a second (no-op) release run;
+        # its `docs:` type is non-releasable and it is still picked up (hidden) in
+        # release-please's next commit-range scan.
         env:
           GH_APP_TOKEN: ${{ steps.app-token.outputs.token }}
+          RELEASE_VERSION: ${{ needs.release-please.outputs.version }}
         run: |
-          CURR_VERSION=$(yq '.version' helm/Chart.yaml)
-          APP_VERSION=$(yq '.appVersion' helm/Chart.yaml)
-
-          # workflow_dispatch: publish the version already in Chart.yaml.
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "chart_version=$CURR_VERSION" >> "$GITHUB_OUTPUT"
-            echo "Releasing existing chart version $CURR_VERSION (appVersion: $APP_VERSION)"
-            exit 0
-          fi
-
-          # If the developer already bumped Chart.version in their commit, honour it.
-          PREV_VERSION=$(git show HEAD~1:helm/Chart.yaml | yq '.version')
-          if [ "$PREV_VERSION" != "$CURR_VERSION" ]; then
-            echo "chart_version=$CURR_VERSION" >> "$GITHUB_OUTPUT"
-            echo "Chart.version already bumped ($PREV_VERSION -> $CURR_VERSION); using as-is."
-            exit 0
-          fi
-
-          # ── Auto-bump based on conventional-commit message ────────────────
-          COMMIT_MSG=$(git log --format='%s' -1)
-          COMMIT_BODY=$(git log --format='%b' -1)
-
-          MAJOR=$(echo "$CURR_VERSION" | cut -d. -f1)
-          MINOR=$(echo "$CURR_VERSION" | cut -d. -f2)
-          PATCH=$(echo "$CURR_VERSION" | cut -d. -f3)
-
-          if echo "$COMMIT_BODY" | grep -qi 'BREAKING CHANGE'; then
-            NEW_VERSION="$((MAJOR + 1)).0.0"
-            BUMP_TYPE="major"
-          elif echo "$COMMIT_MSG" | grep -qE '^feat(\(|:)'; then
-            NEW_VERSION="$MAJOR.$((MINOR + 1)).0"
-            BUMP_TYPE="minor"
-          else
-            NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
-            BUMP_TYPE="patch"
-          fi
-
-          echo "Auto $BUMP_TYPE bump: $CURR_VERSION -> $NEW_VERSION (commit: $COMMIT_MSG)"
-
-          yq -i ".version = \"$NEW_VERSION\"" helm/Chart.yaml
-
-          printf "# %s\n\n%s\n\n" "$NEW_VERSION" "$COMMIT_MSG" \
-            | cat - helm/CHANGELOG.md > /tmp/CHANGELOG.md
-          mv /tmp/CHANGELOG.md helm/CHANGELOG.md
-
           helm-docs --chart-search-root=helm
 
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add helm/Chart.yaml helm/CHANGELOG.md helm/README.md
-          git commit -m "chore(helm): bump chart to $NEW_VERSION"
-          git push "https://x-access-token:${GH_APP_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:main
+          git add helm/README.md
 
-          echo "chart_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+          if git diff --staged --quiet; then
+            echo "Chart README already in sync; nothing to commit."
+          else
+            git commit -m "docs: regenerate chart README for ${RELEASE_VERSION} [skip ci]"
+            git push "https://x-access-token:${GH_APP_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:main
+          fi
 
       - name: Set up Helm
         uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2 # v5.0.0
@@ -130,11 +137,28 @@ jobs:
           echo "Packaged: $(ls /tmp/helm-packages)"
 
       - name: Push chart to GitHub Container Registry
+        env:
+          CHART_VERSION: ${{ needs.release-please.outputs.version }}
+          REPO_OWNER: ${{ github.repository_owner }}
         run: |
           helm push \
-            "/tmp/helm-packages/firebolt-instance-${STEPS_CHART_OUTPUTS_CHART_VERSION}.tgz" \
-            "oci://${{ env.GHCR_REGISTRY }}/${{ github.repository_owner }}/${{ env.HELM_CHARTS_NAMESPACE }}"
-          echo "Pushed firebolt-instance:${STEPS_CHART_OUTPUTS_CHART_VERSION} to GHCR"
+            "/tmp/helm-packages/firebolt-instance-${CHART_VERSION}.tgz" \
+            "oci://${GHCR_REGISTRY}/${REPO_OWNER}/${HELM_CHARTS_NAMESPACE}"
+          echo "Pushed firebolt-instance:${CHART_VERSION} to GHCR"
 
+      - name: Job summary
         env:
-          STEPS_CHART_OUTPUTS_CHART_VERSION: ${{ steps.chart.outputs.chart_version }}
+          CHART_VERSION: ${{ needs.release-please.outputs.version }}
+          TAG_NAME: ${{ needs.release-please.outputs.tag_name }}
+          REPO_OWNER: ${{ github.repository_owner }}
+        run: |
+          {
+            echo "### Helm chart published :rocket:"
+            echo ""
+            echo "| Field | Value |"
+            echo "|-------|-------|"
+            echo "| **Chart** | \`firebolt-instance\` |"
+            echo "| **Version** | \`${CHART_VERSION}\` |"
+            echo "| **Release tag** | \`${TAG_NAME}\` |"
+            echo "| **Registry** | \`oci://${GHCR_REGISTRY}/${REPO_OWNER}/${HELM_CHARTS_NAMESPACE}\` |"
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/helm-test.yaml b/.github/workflows/helm-test.yaml
@@ -60,7 +60,11 @@ jobs:
   helm-test:
     name: helm-test (k8s ${{ matrix.k8s-version }})
     needs: detect
-    if: needs.detect.outputs.docs_only != 'true'
+    # Skip release-please's release PRs: they only bump Chart.yaml `version` +
+    # CHANGELOG.md over templates that already passed e2e on the feature PR, so
+    # re-running the 45-minute kind suite adds no coverage and a flake there
+    # would needlessly block the release.
+    if: needs.detect.outputs.docs_only != 'true' && !startsWith(github.head_ref, 'release-please')
     runs-on: ubuntu-latest
     timeout-minutes: 45
     permissions:
diff --git a/.github/workflows/pr-title.yaml b/.github/workflows/pr-title.yaml
@@ -0,0 +1,60 @@
+---
+# release-please derives the next chart version and CHANGELOG from the
+# conventional-commit subject of each squash-merged PR, so the PR title IS the
+# commit message that reaches main. This gate enforces that contract.
+name: PR Title
+
+on:
+  pull_request:
+    # 'edited' is required so that fixing a failed title (which changes only the
+    # title, not the commits) re-triggers validation. The default activity types
+    # (opened, synchronize, reopened) do not cover title edits.
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - edited
+
+permissions: {}
+
+jobs:
+  validate:
+    name: PR Title
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    if: ${{ !startsWith(github.head_ref, 'dependabot') && !startsWith(github.head_ref, 'release-please') }}
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # List of allowed commit types
+          types: |
+            build
+            chore
+            ci
+            docs
+            feat
+            fix
+            perf
+            refactor
+            revert
+            style
+            test
+
+          subjectPattern: ^[a-z0-9_].*\((#[0-9]+|[A-Z]+-[0-9]+)\)$
+          requireScope: false
+          validateSingleCommit: false
+          subjectPatternError: |
+            The subject "{subject}" found in the pull request title "{title}" didn't match the configured pattern.
+
+            We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+            Our CI is configured to forbid PRs with titles that don't follow this standard.
+            That's it, all commits landing in the `main` branch must be formatted in this way.
+            Please make sure you read and understand this convention.
+
+            The subject must not start with a capital letter, and must end with an issue
+            reference in parentheses: either a GitHub issue like "(#123)" or a tracker
+            ticket like "(FB-1234)".
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  "helm": "0.2.0"
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## What this project does
 
-Helm chart that runs a Firebolt instance on Kubernetes: an Envoy gateway that routes by `X-Firebolt-Engine` header, the Pensieve metadata service, a bundled or external PostgreSQL for metadata storage, and one or more `firebolt-core` query engines as StatefulSets. The chart is published as `firebolt-instance` to `oci://ghcr.io/firebolt-db/helm-charts` on every push to `main` that touches `helm/`.
+Helm chart that runs a Firebolt instance on Kubernetes: an Envoy gateway that routes by `X-Firebolt-Engine` header, the Pensieve metadata service, a bundled or external PostgreSQL for metadata storage, and one or more `firebolt-core` query engines as StatefulSets. The chart is published as `firebolt-instance` to `oci://ghcr.io/firebolt-db/helm-charts` when a release-please release PR is merged to `main` (see project-specific rules).
 
 ## Repo structure
 
@@ -28,7 +28,7 @@ Helm chart that runs a Firebolt instance on Kubernetes: an Envoy gateway that ro
 ├── docs/                     # user-facing docs, Mintlify MDX (docs.json drives nav; see docs/AGENTS.md for style)
 ├── docs-internal/            # Firebolt-internal docs (e.g. the make dev / floci flow), plain Markdown
 ├── .github/
-│   ├── workflows/            # helm-validate, helm-release-cd, gha-lint, helm-test
+│   ├── workflows/            # helm-validate, helm-release-cd (release-please), pr-title, gha-lint, helm-test
 │   └── ISSUE_TEMPLATE/
 ├── static/                   # chart icon
 ├── .pre-commit-config.yaml   # helm-docs, helm lint --strict, helm template dry-run
@@ -90,7 +90,7 @@ You MUST keep documentation in sync with code. When making changes:
 
 - **AGENTS.md** — update the relevant `AGENTS.md` (root or `helm/AGENTS.md`) if you change structure, conventions, public surface, commands, or config formats. If your change makes existing AGENTS.md content wrong, fix it before finishing.
 - **`helm/values.yaml` annotations** — every value rendered into `helm/README.md` is documented inline via `# --` comments processed by `helm-docs`. When you add, rename, remove, or change the meaning of a value, update its annotation in the same change. Then regenerate `helm/README.md` via `make docs` (or let the pre-commit `helm-docs` hook do it on commit).
-- **`helm/CHANGELOG.md`** — the `helm-release-cd` workflow prepends a new entry on each release based on the conventional-commit message of the merge commit. You do not normally hand-edit this file; you DO need to write a conventional-commit message (`feat:` / `fix:` / `chore:` / etc.) so the auto-bump and changelog entry are correct.
+- **`helm/CHANGELOG.md`** — release-please owns this file, prepending a section for each release from the conventional-commit history since the last release. You do not hand-edit it; you DO need conventional-commit PR titles (`feat:` / `fix:` / `chore(deps):` / etc.) so the version bump and changelog entry are correct.
 - **`README.md` (root)** — overview-only. Update when your change affects what a human reader needs to know about what the project is or how to run it. Implementation detail belongs in this file or `helm/AGENTS.md`, not the README.
 - **`helm/README.md`** — never hand-edit. It is regenerated.
 
@@ -119,7 +119,7 @@ Code is not done until it is covered by tests where tests are reasonable.
 Every change is tracked and lands through a branch and a pull request — no exceptions.
 
 - **A documented issue comes first.** Every task MUST have a corresponding issue before any work starts — a Linear ticket or a GitHub issue. If none exists, create one (GitHub issues use the templates under `.github/ISSUE_TEMPLATE/`). No issue, no work.
-- **Never touch `main` directly.** You MUST NEVER work in, commit to, or push to `main`. All work happens on a feature branch and merges via a reviewed PR. (`main` is only ever advanced by merging a PR or by the release workflow's automated version-bump commit — see project-specific rules.)
+- **Never touch `main` directly.** You MUST NEVER work in, commit to, or push to `main`. All work happens on a feature branch and merges via a reviewed PR. (`main` is only ever advanced by merging a PR — including release-please's automated release PR — see project-specific rules.)
 - **Branch names tie the branch to its issue**, so work is traceable. Prefix the branch with the tracker identifier:
   - Linear: `FB-<number>-<short-kebab-description>` (e.g. `FB-790-ci-testing`).
   - GitHub issue: `<issue-number>-<short-kebab-description>`.
@@ -139,7 +139,7 @@ Linear specifics:
 
 ## Project-specific rules
 
-- **Conventional commits drive releases.** The `helm-release-cd` workflow on `main` parses the merge-commit subject. `feat:` bumps minor, `fix:`/`chore:`/anything-else bumps patch, and a body containing `BREAKING CHANGE` bumps major. Chart version in `helm/Chart.yaml` is auto-bumped and committed back to `main` by a GitHub App; `helm/CHANGELOG.md` is prepended; `helm/README.md` is regenerated; the chart is packaged and pushed to GHCR. If you bump `helm/Chart.yaml` `version` manually in your commit, the workflow honours it as-is and skips the auto-bump.
+- **Conventional commits drive releases via release-please.** The `helm-release-cd` workflow on `main` runs [release-please](https://github.com/googleapis/release-please) (config: `release-please-config.json`, state: `.release-please-manifest.json`), which accumulates conventional-commit merges onto an automated release PR. `feat:` bumps minor, `fix:`/`perf:`/`revert:`/`chore(deps):` bump patch, and `BREAKING CHANGE` bumps minor while pre-1.0 (`bump-minor-pre-major`). Merging that release PR bumps `helm/Chart.yaml` `version`, prepends `helm/CHANGELOG.md`, tags `<version>` (bare SemVer, no `v` — matching the chart version and OCI tag), and cuts a GitHub release; only then does the `release-chart` job regenerate `helm/README.md`, package the chart, and push it to GHCR. Do NOT hand-bump `helm/Chart.yaml` `version` — release-please owns it. `appVersion` is the exception: it is managed by the upstream image-release automation, not release-please.
 - **`appVersion` is the shared default image tag.** `helm/Chart.yaml`'s `appVersion` is the default for both `engineSpec.image.tag` and `metadata.image.tag`, and both image registries now publish matching `debug-` / `release-` prefixed tags. Override `metadata.image.tag` only when the metadata service must run a version other than the engine.
 - **GitHub Actions are pinned to commit SHAs.** All `uses:` references in `.github/workflows/*` use full 40-char SHAs with a version comment. `actionlint` and `zizmor` run on every push/PR that touches `.github/`. New actions you introduce MUST follow the same pinning convention.
 - **Pre-commit hook quirk: first-run helm-docs aborts the commit.** The `helm-docs` pre-commit hook regenerates `helm/README.md` and stages the result; if the regeneration changes the file, the commit aborts so you can re-run `git commit` with the now-staged README.md included. This is documented in `.pre-commit-config.yaml` and is intentional.
diff --git a/helm/AGENTS.md b/helm/AGENTS.md
diff --git a/release-please-config.json b/release-please-config.json
