Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/02-observability/sentry-ci-integration.md
T

201 lines
13 KiB
Markdown

# 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.)_