Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,200 @@
|
||||
# Sentry CI Integration — Release-Tagging + Source-Map-Upload
|
||||
|
||||
**Status:** completed (workflows shipped; `SENTRY_AUTH_TOKEN` live in Gitea + app env per operator checklist A5; release-artifact proof remains per-CI-run verification)
|
||||
**Task-ID:** #32
|
||||
**Phase:** 02
|
||||
**Estimated Effort:** 0.5 Tag
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Ohne CI-Integration:
|
||||
|
||||
- Sentry-Releases werden nicht angelegt — Errors zeigen kein "First Seen In Release", kein "Resolved In Release", keine Regression-Detection
|
||||
- Source-Maps werden bei Web-Builds zwar lokal hochgeladen wenn `SENTRY_AUTH_TOKEN` gesetzt ist (siehe `sentry-wiring-web.md` Step 9), aber **nicht in CI** → Production-Build-Source-Maps fehlen, Stack-Traces bleiben minified
|
||||
- Keine Commit-Korrelation (`set-commits --auto`) → bei einem neuen Issue weiß man nicht, welcher Commit es eingeführt hat
|
||||
- Keine Deploy-Markierung in Sentry → keine "Deploy"-Linien im Performance-Dashboard
|
||||
|
||||
Wir haben **zwei** CI-Targets: `.github/workflows/` (GitHub-Mirror) und `.gitea/workflows/` (selbst-gehostete Gitea-Instance). Beide müssen die gleichen Sentry-Schritte ausführen.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `02-observability/sentry-selfhost-setup.md` — Sentry-Org + Projects existieren, Auth-Token kann ausgestellt werden
|
||||
- `02-observability/sentry-wiring-api-worker.md` — `SENTRY_RELEASE` env wird vom Code konsumiert
|
||||
- `02-observability/sentry-wiring-web.md` — Vite-Plugin ist konfiguriert, braucht nur `SENTRY_AUTH_TOKEN` aus CI
|
||||
|
||||
## Blocks
|
||||
|
||||
- Keine harten Blocks. Aber alle Phase-03+ Refactorings profitieren von sauberer Release-Korrelation — ohne dieses Task wären die Tags da, aber unverknüpft.
|
||||
|
||||
## Approach
|
||||
|
||||
**Gewählt:** Ein Composite-Action / Reusable-Workflow-Snippet, das in beiden CI-Systemen (GitHub + Gitea — Gitea-Actions ist GitHub-Actions-kompatibel) wiederverwendet wird. Ein Sentry-CLI-Schritt nach dem Build, der:
|
||||
|
||||
1. Release anlegt: `sentry-cli releases new $GIT_SHA`
|
||||
2. Source-Maps uploaden: `sentry-cli sourcemaps upload --release $GIT_SHA ./apps/web/build` (für Web — API + Worker haben kein Source-Map-Upload nötig, weil Node-SSR den Stack mit File-Pfaden bekommt)
|
||||
3. Commits dem Release zuordnen: `sentry-cli releases set-commits $GIT_SHA --auto`
|
||||
4. Deploy markieren: `sentry-cli releases deploys $GIT_SHA new -e $ENVIRONMENT`
|
||||
|
||||
Statt redundanter Steps in beiden Workflow-Dateien: ein Reusable-Workflow in `.github/workflows/_sentry-release.yml` + ein Gitea-Equivalent. Beide aufrufen einen Shell-Helper `scripts/ci/sentry-release.sh`, der die eigentliche Logik enthält. So bleibt die Logik DRY.
|
||||
|
||||
**Sentry-CLI installieren:** offizielles `npx @sentry/cli` (kein binary-Download nötig — `npx` ist in beiden CI-Runtimes verfügbar).
|
||||
|
||||
**Secrets:**
|
||||
- `SENTRY_AUTH_TOKEN` — User-Token mit `project:releases`-Scope (NICHT mit Org-Admin-Scope)
|
||||
- `SENTRY_ORG` — z.B. `boilerplate`
|
||||
- `SENTRY_PROJECT` — wird pro Step gesetzt (`boilerplate-api`, `boilerplate-worker`, `boilerplate-web`)
|
||||
- `SENTRY_URL` — self-hosted URL, z.B. `https://sentry.<staging-domain>` (default ist `sentry.io`, MUSS gesetzt sein)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Shell-Helper anlegen** — `scripts/ci/sentry-release.sh`:
|
||||
- Args: `--project <name>` `--environment <env>` `--release <sha>` `--sourcemaps <path|none>`
|
||||
- Ruft `sentry-cli releases new`, optional `sourcemaps upload`, `releases set-commits --auto`, `releases deploys`
|
||||
- Set `set -euo pipefail`, klare Fehler bei fehlenden Env-Vars
|
||||
- Files: `scripts/ci/sentry-release.sh`, `scripts/ci/sentry-release.test.sh` (bats oder bash-mit-asserts)
|
||||
- Commit: `02-observability/sentry-ci: add sentry-release shell helper`
|
||||
|
||||
2. **GitHub-Reusable-Workflow** — `.github/workflows/_sentry-release.yml`:
|
||||
- `workflow_call` mit Inputs `project`, `environment`, `sourcemaps-path` (optional)
|
||||
- Secrets: `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_URL`
|
||||
- Step: `node -v && npx --yes @sentry/cli --version`
|
||||
- Step: `bash scripts/ci/sentry-release.sh --project ${{ inputs.project }} --environment ${{ inputs.environment }} --release ${{ github.sha }} --sourcemaps ${{ inputs.sourcemaps-path || 'none' }}`
|
||||
- Files: `.github/workflows/_sentry-release.yml`
|
||||
- Commit: `02-observability/sentry-ci: add github reusable workflow for sentry release`
|
||||
|
||||
3. **Gitea-Reusable-Workflow** — `.gitea/workflows/_sentry-release.yml` analog. Gitea-Actions unterstützt `workflow_call` ab Version 1.21 — falls die Staging-Gitea-Instance älter ist, alternativ als Action-YAML in `.gitea/actions/sentry-release/action.yml` (composite action).
|
||||
- Files: `.gitea/workflows/_sentry-release.yml` ODER `.gitea/actions/sentry-release/action.yml`
|
||||
- Commit: `02-observability/sentry-ci: add gitea reusable workflow for sentry release`
|
||||
|
||||
4. **Build-Jobs aufrufen den Workflow** — bestehende `build`-Jobs in `.github/workflows/ci.yml` (und Gitea-Equivalent) um Aufrufe ergänzen:
|
||||
- Nach API-Build: `uses: ./.github/workflows/_sentry-release.yml` mit `project: boilerplate-api`
|
||||
- Nach Worker-Build: `... project: boilerplate-worker`
|
||||
- Nach Web-Build: `... project: boilerplate-web, sourcemaps-path: apps/web/build/client`
|
||||
- `environment` = `production` für main-Branch, `staging` für `staging`-Branch, `preview` sonst
|
||||
- Files: `.github/workflows/ci.yml`, `.gitea/workflows/ci.yml`
|
||||
- Commit: `02-observability/sentry-ci: wire release jobs into ci workflows`
|
||||
|
||||
5. **Secrets dokumentieren** — `docs/observability/sentry-selfhost.md` erweitern um Sektion "CI-Secrets":
|
||||
- Wie man in Sentry-UI einen Auth-Token erstellt (Settings → Account → API → Auth Tokens, Scope `project:releases`)
|
||||
- Wie man die Secrets in GitHub (`Settings → Secrets → Actions`) und Gitea (`Repo Settings → Secrets`) ablegt
|
||||
- Rotation-Strategie (alle 6 Monate)
|
||||
- Files: `docs/observability/sentry-selfhost.md` (Erweiterung)
|
||||
- Commit: `02-observability/sentry-ci: document CI secrets for sentry release`
|
||||
|
||||
6. **Smoke-Test CI** — einen Commit auf einem Test-Branch pushen und prüfen ob in Sentry-UI:
|
||||
- Release `<git-sha>` erscheint
|
||||
- Commits sind zugeordnet (mind. 1 Commit-Eintrag sichtbar)
|
||||
- Web-Project hat Source-Map-Artifacts > 0
|
||||
- Deploy-Marker auf Performance-Dashboard sichtbar
|
||||
- Files: keine (Operations-Schritt)
|
||||
- Commit: keiner
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:**
|
||||
- `scripts/ci/sentry-release.test.sh` — Helper mit Mock-`sentry-cli` (PATH-Override) testen: korrekte Args werden weitergereicht, Exit-Code bei fehlendem Env-Var ist != 0
|
||||
- **Integration-Test:**
|
||||
- Test-Workflow `.github/workflows/test-sentry-release.yml` der auf einem Throwaway-Branch läuft und nur den Sentry-Step ausführt — manuell triggerbar via `workflow_dispatch`
|
||||
- **E2E (Staging-CI):**
|
||||
- Tatsächlicher Push auf `agent/phase-02-sentry-ci` → Release in Sentry-UI vorhanden
|
||||
- **Coverage-Target:** N/A für Shell-Helper, aber `set -euo pipefail` + alle Branches im Helper getestet
|
||||
- **Test-Files:** wie oben
|
||||
|
||||
**NICHT als completed markieren bevor:**
|
||||
- Helper-Tests grün
|
||||
- mind. 1 erfolgreicher CI-Lauf (GitHub UND Gitea) mit Sentry-Release-Artefakten in der UI sichtbar
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `scripts/ci/sentry-release.sh` existiert, ist getestet, set-euo-pipefail
|
||||
- [ ] GitHub-Reusable-Workflow oder Action vorhanden
|
||||
- [ ] Gitea-Equivalent vorhanden
|
||||
- [ ] Build-Jobs rufen den Sentry-Release-Schritt für API, Worker, Web auf
|
||||
- [ ] `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_URL` in beiden CI-Systemen als Secrets hinterlegt
|
||||
- [ ] Mind. 1 Release pro Project in Sentry sichtbar mit Commit-Korrelation
|
||||
- [ ] Mind. 1 Web-Release mit hochgeladenen Source-Maps (Artifacts > 0)
|
||||
- [ ] Deploy-Marker auf Performance-Dashboard sichtbar
|
||||
- [ ] Doku-File erweitert um CI-Secrets-Sektion
|
||||
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün (keine TS-Änderungen)
|
||||
- [ ] Detail-MD Progress Log aktualisiert
|
||||
- [ ] PROGRESS.md Status auf `completed`
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- **Sentry-Steps in CI-Workflow auskommentieren** — Build läuft weiter, nur kein Release-Tagging
|
||||
- **`SENTRY_AUTH_TOKEN`-Secret invalidieren** in Sentry-UI → Steps schlagen fehl, aber Build geht weiter wenn Step als `continue-on-error: true` markiert ist (Default-Empfehlung für non-critical CI-Steps)
|
||||
- **Releases-API-Aufrufe rückgängig** via `sentry-cli releases delete <release>` (manuell, nur falls fehlerhafter Release-Name)
|
||||
- **Commits revertierbar** — alle 4 Commits einzeln revertierbar
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **`SENTRY_AUTH_TOKEN` muss minimal-scoped sein** — nur `project:releases`. NICHT `org:admin`, NICHT `member:admin`. Damit kann ein geleakter Token max. Source-Maps stehlen / Releases manipulieren, nicht ganze Projects löschen.
|
||||
- **Token-Rotation alle 6 Monate** — Kalendererinnerung im Operator-Onboarding setzen.
|
||||
- **Token NIEMALS in Logs printen** — Helper-Skript mit `set +x` und `echo "::add-mask::$SENTRY_AUTH_TOKEN"` (GitHub) bzw. Gitea-Equivalent absichern.
|
||||
- **Source-Maps sind kein Secret pro se** (Sentry hat sie ja eh), aber sie offenbaren Quellcode-Struktur — Upload nur nach erfolgreichem Build, niemals nach failed Test (kein partieller Source-Map-Upload).
|
||||
- **`--auto`-Commit-Korrelation** liest Git-Log und sendet Commit-SHAs + -Subjects an Sentry → Commit-Messages sollten keine Secrets/PII enthalten (Standard, aber Hinweis im Doku-File).
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit dieser Detail-MD — soll prüfen ob Gitea-Version `workflow_call` unterstützt oder ob composite-action der Weg ist
|
||||
- **Implementation Shell-Helper:** `general-purpose`-Subagent für Step 1
|
||||
- **Implementation CI-Workflows:** `general-purpose`-Subagent für Steps 2-4
|
||||
- **Doku:** kleiner `general-purpose`-Subagent für Step 5
|
||||
- **Verification:** `general-purpose`-Subagent für CI-Smoke + Sentry-UI-Check
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Task-Completion
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Secrets in GitHub + Gitea hinterlegen (siehe Step 5)
|
||||
2. Branch `agent/phase-02-sentry-ci` pushen → CI läuft durch
|
||||
3. Build-Logs prüfen:
|
||||
```
|
||||
[sentry-cli] Created release <git-sha>
|
||||
[sentry-cli] Source map upload complete (X files)
|
||||
[sentry-cli] Setting commits for release <git-sha>
|
||||
[sentry-cli] Created deploy of <git-sha> to environment staging
|
||||
```
|
||||
4. Sentry-UI öffnen:
|
||||
- `https://sentry.<staging-domain>/<org>/boilerplate-web/releases/<git-sha>/`
|
||||
- Artifacts-Tab: > 0 Files
|
||||
- Commits-Tab: > 0 Commits
|
||||
5. Künstlicher Error auf Web (`/__test/client-throw`) → Issue zeigt "First Seen In Release: <git-sha>" mit unminifiziertem Stack-Trace
|
||||
6. Wenn alles grün: PR → main; Production-CI nutzt dann denselben Workflow
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
- **2026-05-27 status reconciliation:** `docs/improvement-plan/OPERATOR-CHECKLIST.md`
|
||||
A5 verifies `SENTRY_AUTH_TOKEN` is live on all three apps and the
|
||||
Gitea secret is set. That closes the stale token/env caveat and matches
|
||||
`PROGRESS.md` status `completed` for #32. This is not a blanket claim
|
||||
that every future CI run has produced Sentry artifacts; release,
|
||||
source-map, commit-correlation, and deploy-marker checks remain the
|
||||
per-run verification steps in the staging section above.
|
||||
|
||||
## Progress Log
|
||||
|
||||
- 2026-05-17 — `6a98e03d` — add scripts/ci/sentry-release.sh helper + bash test harness (5 tests green)
|
||||
- 2026-05-17 — `9c2ee9a6` — add .github/workflows/_sentry-release.yml reusable workflow
|
||||
- 2026-05-17 — `86469246` — add .gitea/workflows/_sentry-release.yml + .gitea/actions/sentry-release/action.yml composite-action fallback
|
||||
- 2026-05-17 — `056663d0` — wire sentry-release-{api,worker,web} jobs into .github + .gitea ci.yml (gated on docker-smoke); add Mark-Sentry-deploy post-deploy step to .gitea/workflows/deploy.yml
|
||||
- 2026-05-17 — `37f23fa6` — document CI Secrets section in docs/observability/sentry-selfhost.md (mint/store/rotate); add SENTRY_URL to .env.example
|
||||
- 2026-05-27 — docs/status reconciliation — A5 verifies the Sentry auth
|
||||
token is live in Gitea + app env, superseding the stale
|
||||
`ci-smoke-pending` status caveat without changing the per-run artifact
|
||||
verification checklist.
|
||||
|
||||
## Gitea workflow_call support
|
||||
|
||||
Gitea Actions `workflow_call` requires runner v1.21+. Status on the
|
||||
staging Gitea cannot be checked from this agent's environment. To
|
||||
stay safe we ship BOTH a workflow_call file
|
||||
(`.gitea/workflows/_sentry-release.yml`) AND a composite-action
|
||||
fallback (`.gitea/actions/sentry-release/action.yml`). The CI
|
||||
workflow currently calls the former — if the runner rejects
|
||||
workflow_call, swap the three job blocks for explicit jobs that
|
||||
`uses: ./.gitea/actions/sentry-release` after checkout.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
_(Optional — typische Stolperfallen: Gitea-`workflow_call` braucht v1.21+; `sentry-cli` braucht `SENTRY_URL` weil sonst Default `sentry.io` verwendet wird; Source-Map-Pfade müssen mit Build-Output exakt matchen.)_
|
||||
Reference in new issue
Block a user