ci: harden release chart doc sync push against races (FB-2030) (#31)

## Background
FB-2030: the release workflow can fail when it commits regenerated chart
docs and then loses a push race to another commit on `main`.

## Summary
- set the `release-chart` checkout to `fetch-depth: 0` so rebase has a
reliable merge base.
- replace the one-shot push in `Sync generated chart README to released
version` with a 3-attempt retry loop.
- after a rejected push, fetch latest authenticated `main` and rebase
before retrying.
- document the race condition and mitigation in `AGENTS.md` Known
issues.

## Test Plan
- [x] `actionlint .github/workflows/helm-release-cd.yaml`

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: fstr

.github/workflows/helm-release-cd.yaml

@@ -71,6 +71,7 @@ jobs:
         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
@@ -113,7 +114,24 @@ jobs:
             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
+            PUSH_URL="https://x-access-token:${GH_APP_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+            for attempt in 1 2 3; do
+              if git push "$PUSH_URL" HEAD:main; then
+                break
+              fi
+
+              if [ "$attempt" -eq 3 ]; then
+                echo "Failed to push chart README sync after ${attempt} attempts." 1>&2
+                exit 1
+              fi
+
+              git fetch "$PUSH_URL" main
+              if ! git rebase FETCH_HEAD; then
+                git rebase --abort || true
+                echo "Failed to rebase chart README sync onto latest main." 1>&2
+                exit 1
+              fi
+            done
           fi
 
       - name: Set up Helm

AGENTS.md

@@ -134,6 +134,7 @@ Ongoing limitations, framework footguns, and environment traps that still affect
 - Remove the entry when the underlying issue is fixed — do not leave solved history behind.
 
 - Symptom: GitHub Actions workflows that use `azure/setup-helm` with `version: "latest"` can start failing or changing behavior unexpectedly. Cause: the action matches upstream Helm tarball names verbatim and `latest` can silently advance across major versions, including to Helm v4. Resolution: pin an explicit Helm v3 patch in both validation and release workflows until the v4 behavioral differences have been audited and adopted intentionally.
+- Symptom: release jobs that commit generated chart docs back to `main` can fail with `! [rejected] HEAD -> main (fetch first)` when another commit lands after checkout. Cause: a single push attempt from a stale local base, with checkout credentials disabled. Resolution: keep release checkouts at full history and wrap the push in a retry loop that fetches and rebases on the latest authenticated `main` between attempts, failing only after explicit retries are exhausted.
 
 ## Project-specific rules