# 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.` (default ist `sentry.io`, MUSS gesetzt sein) ## Implementation Steps 1. **Shell-Helper anlegen** — `scripts/ci/sentry-release.sh`: - Args: `--project ` `--environment ` `--release ` `--sourcemaps ` - 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 `` 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 ` (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 [sentry-cli] Source map upload complete (X files) [sentry-cli] Setting commits for release [sentry-cli] Created deploy of to environment staging ``` 4. Sentry-UI öffnen: - `https://sentry.//boilerplate-web/releases//` - Artifacts-Tab: > 0 Files - Commits-Tab: > 0 Commits 5. Künstlicher Error auf Web (`/__test/client-throw`) → Issue zeigt "First Seen In Release: " 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.)_