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

13 KiB

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: " 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.)