RavenDB-26535 Kubernetes Operator: Release Process

.claude/skills/pre-release-report.md

@@ -0,0 +1,90 @@
+---
+name: pre-release-report
+description: Run if user wants to prepare for release. Six-pass audit of the repo before cutting a release. Passes 1-2 (CSV markers, samples) propose changes for user approval and commit them. Passes 3-6 (breaking changes, Helm parity, reviewers, dependencies) report findings; the user directs follow-up.
+---
+
+Six-pass pre-release audit. Run them in order. End with a structured summary.
+
+Use the current branch's ticket prefix (e.g., `RavenDB-26535`) for any commit subjects. Determine it from `git branch --show-current`.
+
+## Pass 1 — CSV markers (action: propose → confirm → apply → commit)
+
+Walk `api/v1/*.go`. For every exported field with a JSON tag, decide whether it needs a `+operator-sdk:csv:customresourcedefinitions:` marker.
+
+**Skip:**
+- `Spec`, `Status`, `Items`, `TypeMeta`, `ObjectMeta`, `ListMeta` — structural plumbing.
+- Embedded k8s core types (`corev1.VolumeSource`, `corev1.EnvVar`, `corev1.SecretReference`).
+- Pure container fields whose descriptors come from nested children (e.g., `Data`, `Logs`, `RavenDB`, `Audit` in `StorageSpec` — descriptors live on `Size`, `StorageClassName`, etc., reached via `storage.data.size` etc.).
+
+**Mark:** spec fields → `type=spec`, status fields → `type=status`. Format:
+`// +operator-sdk:csv:customresourcedefinitions:type=<spec|status>,displayName="<DisplayName>"`
+
+DisplayName: CamelCase → "Space-Separated Words"; keep acronyms (URL, ID, IP, EIP, CA, TCP, DNS); prefer domain-clear (`CertSecretRef` → "Certificate Secret"). Match the style of existing markers in the same file. Do NOT add `description="..."` — operator-sdk's parser rejects it at this level.
+
+Show proposals as `file:line  field  →  marker`, ask for confirmation/overrides, apply, run `make verify-samples` and (if available) `make bundle` in WSL to verify operator-sdk parses everything. Commit: `<ticket>: refresh CSV markers in api/v1`.
+
+## Pass 2 — Samples (action: validate + propose updates → confirm → apply → commit)
+
+First, run `make verify-samples`. If it fails, the strict-unmarshal error names the file/field — fix and re-run.
+
+Then, judgment pass: diff `api/v1/` spec types against the most recent release tag (`git describe --tags --abbrev=0`).
+
+For incremental additions (new optional fields, new array entries on existing types), ask: "Should this field appear in `ravendb_v1_ravendbcluster_letsencrypt.yaml`, `..._selfsigned.yaml`, both, or neither?"
+
+For changes that introduce a fundamentally distinct use case — a new `mode:` value, a new external-access provider type, a new storage backend, a new auth scheme — propose adding a NEW sample file: `ravendb_v1_ravendbcluster_<scenario>.yaml`. The user may also request a new sample even for incremental changes if they want a separate example. Register any new sample in `config/samples/kustomization.yaml` so operator-sdk folds it into alm-examples.
+
+Apply approved additions/files. Re-run `make verify-samples`. Commit: `<ticket>: update config/samples for new spec fields`.
+
+## Pass 3 — CRD breaking-change review (report only)
+
+Render the CRD at the most recent release tag and at HEAD, then diff. Render with `kustomize build config/crd | yq` (or operator-sdk equivalent). Surface:
+
+| Change | Severity | Why it matters |
+|---|---|---|
+| Removed field | High | Breaks users who set it |
+| Type change | High | Wire-incompatible |
+| New required field, no default | High | Breaks existing CRs on upgrade |
+| Narrowed enum or smaller min/max | Medium | Breaks users at the boundary |
+| Changed default | Medium | Silent behavior change |
+
+Output severity, field path, before → after. Do NOT auto-fix — these are deliberate decisions (keep with a major version bump, document migration, or revert).
+
+## Pass 4 — Helm chart parity (report only)
+
+`helm/chart/templates/` and `config/` are maintained in parallel. Diff them across:
+- **RBAC**: verbs/resources/apiGroups in `config/rbac/role.yaml` vs `helm/chart/templates/rbac.yaml` (or equivalent).
+- **Manager Deployment**: env vars, volume mounts, args, resource limits in `config/manager/manager.yaml` vs `helm/chart/templates/deployment.yaml`.
+- **Webhook**: cert-manager Issuer/Certificate refs, service ports.
+
+Report drift as `area | config has | helm has | risk`. Do NOT auto-fix — which side is canonical depends on what the change was for.
+
+## Pass 5 — Reviewer list (report + interactive)
+
+Read `bundle/ravendb-operator/ci.yaml`. Surface the current `reviewers:` list (or note absence — without it OperatorHub auto-merge doesn't fire). Ask: "Is this list current? Anyone to add or remove?" If the user wants edits, propose, confirm, apply, commit `<ticket>: refresh OperatorHub reviewers list`.
+
+## Pass 6 — Dependencies audit (report + interactive, top-level only)
+
+Surface pin vs latest for these only — don't go deep into transitive Go modules:
+
+- `OPERATOR_SDK_VERSION` in `Makefile` vs latest `operator-framework/operator-sdk` GitHub release.
+- `CONTROLLER_TOOLS_VERSION`, `KUSTOMIZE_VERSION`, `ENVTEST_VERSION`, `GOLANGCI_LINT_VERSION` in `Makefile`.
+- `go` directive in `go.mod` vs current stable Go.
+- cert-manager version in `.github/workflows/release.yml` smoke-test URL.
+- GitHub Action versions in `.github/workflows/*.yml` — surface floating tags (`@v3`, `@v4`); recommend SHA pinning where missing.
+
+Report as `dep | pinned | latest | gap | recommendation`. Recommendation tone: "consider bumping" or "looks current". Do NOT auto-bump — bumps need a deliberate test cycle, not a release-prep slipstream. Ask the user if they want to schedule any bumps as separate work.
+
+## Final summary
+
+```
+Pre-release report — <ticket>
+=============================
+Pass 1 (CSV markers):     <committed sha | "no gaps">
+Pass 2 (Samples):         <committed sha | "no updates needed">
+Pass 3 (CRD breaking):    <N items by severity>
+Pass 4 (Helm parity):     <N drift items>
+Pass 5 (Reviewers):       <committed sha | "current">
+Pass 6 (Dependencies):    <N items behind>
+```
+
+After this report, the user has a clear picture of what's actionable before invoking `prepare-release.yml`.

.github/workflows/lint-workflows.yml

@@ -0,0 +1,26 @@
+name: Lint workflows
+
+# Runs on every workflow-touching PR. Catches YAML errors, deprecated action versions,
+# unset secrets, and shellcheck warnings on inline `run:` blocks.
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/**'
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download actionlint
+        run: |
+          bash <(curl -sSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.7
+          ./actionlint -version
+
+      - name: Run actionlint
+        run: ./actionlint -color

.github/workflows/operator-ci.yml

@@ -36,7 +36,7 @@ jobs:
 
       - name: Install gotestsum (if cache miss)
         if: steps.cache-gts.outputs.cache-hit != 'true'
-        run: go install gotest.tools/gotestsum@${GOTESTSUM_VERSION}
+        run: go install "gotest.tools/gotestsum@${GOTESTSUM_VERSION}"
 
       - name: Install setup-envtest tool
         run: go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
@@ -49,7 +49,7 @@ jobs:
           key: ${{ runner.os }}-envtest-${{ env.K8S_VER }}
 
       - name: Select envtest Kubernetes assets
-        run: echo "KUBEBUILDER_ASSETS=$(setup-envtest use -p path ${K8S_VER})" >> "$GITHUB_ENV"
+        run: echo "KUBEBUILDER_ASSETS=$(setup-envtest use -p path "${K8S_VER}")" >> "$GITHUB_ENV"
 
       - name: Cache Go build and module download
         uses: actions/cache@v4
@@ -100,8 +100,8 @@ jobs:
           set -euo pipefail
           common_args=(
             --namespace ravendb-operator-system
-            --set controllerManager.image.repository=ravendb/ravendb-operator 
-            --set controllerManager.image.tag=ci-${GITHUB_SHA}
+            --set controllerManager.image.repository=ravendb/ravendb-operator
+            --set controllerManager.image.tag="ci-${GITHUB_SHA}"
             --set targetNamespace=test-namespace
             --set provisioning.mode=LetsEncrypt
             --set "provisioning.nodeTags={a,b,c}"

.github/workflows/prepare-release.yml

@@ -0,0 +1,166 @@
+name: Prepare Release
+
+# Phase 1 of the two-phase release flow.
+# Trigger: Actions tab -> Run workflow with target version.
+# Output: a `release: vX.Y.Z` PR labeled `release:auto`, carrying source bumps + helm chart.
+# Merge fires the Release workflow; remove the label first to delay publishing.
+# dry_run=true: apply bumps + upload bundle/helm artifacts; no branch/PR/label mutation.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g. 1.1.0, no v prefix)'
+        required: true
+        type: string
+      dry_run:
+        description: 'Dry run (no PR / branch / label mutations)'
+        required: false
+        type: boolean
+        default: false
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+      dry_run:
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    env:
+      VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/setup-helm@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.3'
+          cache: true
+
+      # Stale samples ship a broken "Try sample CR" form to OperatorHub. Gate first.
+      - name: Verify config/samples are current
+        run: make verify-samples
+
+      - name: Read previous version from Makefile
+        id: prev
+        run: |
+          OLD=$(awk -F'?= ' '/^VERSION \?=/ {print $2}' Makefile)
+          echo "old=$OLD" >> "$GITHUB_OUTPUT"
+          echo "Previous version: $OLD"
+          echo "New version:      $VERSION"
+          if [ "${{ inputs.dry_run }}" = "true" ]; then
+            echo "Mode: DRY RUN (no PR / branch / label mutations)"
+          fi
+
+      - name: Bump source files
+        env:
+          OLD: ${{ steps.prev.outputs.old }}
+        run: |
+          sed -i "s/^VERSION ?=.*/VERSION ?= ${VERSION}/" Makefile
+          sed -i "s/^version:.*/version: ${VERSION}/"   helm/chart/Chart.yaml
+          sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" helm/chart/Chart.yaml
+          # SECURITY.md is bumped manually after the GitHub Release is published.
+
+      - name: Regenerate OLM bundle
+        env:
+          OLD: ${{ steps.prev.outputs.old }}
+        run: |
+          make bundle \
+            VERSION="${VERSION}" \
+            IMG="docker.io/ravendb/ravendb-operator:${VERSION}" \
+            CHANNELS=stable \
+            DEFAULT_CHANNEL=stable
+          make bundle-relocate VERSION="${VERSION}"
+          if [ "${OLD}" != "${VERSION}" ]; then
+            rm -rf "bundle/ravendb-operator/${OLD}"
+          fi
+          CSV="bundle/ravendb-operator/${VERSION}/manifests/ravendb-operator.clusterserviceversion.yaml"
+          # operator-sdk omits containerImage; OperatorHub uses it for catalog display.
+          sed -i "/^    capabilities:/i\\    containerImage: docker.io/ravendb/ravendb-operator:${VERSION}" "$CSV"
+          # operator-sdk emits nodes[0].field; OLM convention is nodes[]. (descriptor lines only).
+          sed -i -E '/^        path: /s|\[0\]|[]|g' "$CSV"
+          # make bundle rewrites the kustomization image tag — revert to keep :latest tracked.
+          git checkout -- config/manager/kustomization.yaml
+
+      - name: Package helm chart
+        run: |
+          helm package helm/chart -d helm/
+          helm repo index helm/ \
+            --url https://ravendb.github.io/ravendb-operator/helm \
+            --merge helm/index.yaml
+
+      - name: Verify no stale OLD refs in new bundle
+        env:
+          OLD: ${{ steps.prev.outputs.old }}
+        run: |
+          if grep -nrE "(^|[^0-9])${OLD}([^0-9]|\$)" "bundle/ravendb-operator/${VERSION}"; then
+            echo "::error::Stale ${OLD} references found in bundle/ravendb-operator/${VERSION}/"
+            exit 1
+          fi
+
+      # ─── Real-mode mutations (skipped on dry_run) ───
+
+      - name: Ensure release:auto label exists
+        if: ${{ !inputs.dry_run }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh label create "release:auto" \
+            --description "On merge, fires the Release workflow automatically. Remove before merging to delay publishing." \
+            --color "0e8a16" \
+            || true   # already exists is fine
+
+      - name: Open release PR
+        if: ${{ !inputs.dry_run }}
+        # peter-evans/create-pull-request v8.1.1 — pinned to SHA per supply-chain best practice.
+        # Auto-stages modified files, commits as github-actions[bot], pushes, opens (or
+        # updates) the PR. Idempotent: re-running for the same VERSION updates in place.
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1
+        with:
+          branch: release/v${{ env.VERSION }}
+          base: main
+          title: "release: v${{ env.VERSION }}"
+          commit-message: "release: v${{ env.VERSION }}"
+          labels: release:auto
+          body: |
+            Auto-generated bumps for v${{ env.VERSION }}.
+
+            On merge with the **release:auto** label still attached, the Release workflow fires:
+            multi-arch image push, kind smoke test, tag, GitHub Release with `install.yaml`.
+            Remove the label before merging to delay publishing. SECURITY.md is bumped
+            manually after publishing.
+
+      # ─── Dry-run-only outputs ───
+
+      - name: Dry run — upload artifacts
+        if: ${{ inputs.dry_run }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: prepare-release-${{ inputs.version }}
+          path: |
+            bundle/ravendb-operator/${{ inputs.version }}/
+            helm/ravendb-operator-${{ inputs.version }}.tgz
+            helm/index.yaml
+
+      - name: Dry run — summary
+        if: ${{ inputs.dry_run }}
+        run: |
+          echo "DRY RUN SUMMARY"
+          echo "==============="
+          echo "Would have:"
+          echo "  - Created branch:  release/v${VERSION}"
+          echo "  - Committed:       Makefile, helm/, bundle/, config/"
+          echo "  - Opened PR:       'release: v${VERSION}' with label release:auto"
+          echo ""
+          echo "Working-tree diff vs HEAD:"
+          git diff --stat HEAD

.github/workflows/release-dryrun.yml

@@ -0,0 +1,46 @@
+name: Release dry-run
+
+# Biweekly dry-run of the full pipeline. Catches deprecated actions, broken URLs,
+# and YAML drift before they bite a real release. Opens a `ci-broken` issue on failure.
+
+on:
+  schedule:
+    - cron: '0 6 1,15 * *'    # 1st and 15th of each month, 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  prepare:
+    uses: ./.github/workflows/prepare-release.yml
+    with:
+      version: '0.0.0-dryrun'
+      dry_run: true
+    secrets: inherit
+
+  publish:
+    needs: prepare
+    uses: ./.github/workflows/release.yml
+    with:
+      version: '0.0.0-dryrun'
+      dry_run: true
+    secrets: inherit
+
+  notify-on-failure:
+    needs: [prepare, publish]
+    if: failure() && github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Biweekly release dry-run failed',
+              body: `The scheduled release dry-run failed.\n\nRun: ${runUrl}\n\nThis usually means the release pipeline has drifted (deprecated action, removed input, broken external URL). Check the run logs and fix before the next real release.`,
+              labels: ['ci-broken']
+            });