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_TOKENgesetzt ist (siehesentry-wiring-web.mdStep 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 werden02-observability/sentry-wiring-api-worker.md—SENTRY_RELEASEenv wird vom Code konsumiert02-observability/sentry-wiring-web.md— Vite-Plugin ist konfiguriert, braucht nurSENTRY_AUTH_TOKENaus 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:
- Release anlegt:
sentry-cli releases new $GIT_SHA - 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) - Commits dem Release zuordnen:
sentry-cli releases set-commits $GIT_SHA --auto - 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 mitproject:releases-Scope (NICHT mit Org-Admin-Scope)SENTRY_ORG— z.B.boilerplateSENTRY_PROJECT— wird pro Step gesetzt (boilerplate-api,boilerplate-worker,boilerplate-web)SENTRY_URL— self-hosted URL, z.B.https://sentry.<staging-domain>(default istsentry.io, MUSS gesetzt sein)
Implementation Steps
-
Shell-Helper anlegen —
scripts/ci/sentry-release.sh:- Args:
--project <name>--environment <env>--release <sha>--sourcemaps <path|none> - Ruft
sentry-cli releases new, optionalsourcemaps 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
- Args:
-
GitHub-Reusable-Workflow —
.github/workflows/_sentry-release.yml:workflow_callmit Inputsproject,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
-
Gitea-Reusable-Workflow —
.gitea/workflows/_sentry-release.ymlanalog. Gitea-Actions unterstütztworkflow_callab 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.ymlODER.gitea/actions/sentry-release/action.yml - Commit:
02-observability/sentry-ci: add gitea reusable workflow for sentry release
- Files:
-
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.ymlmitproject: boilerplate-api - Nach Worker-Build:
... project: boilerplate-worker - Nach Web-Build:
... project: boilerplate-web, sourcemaps-path: apps/web/build/client environment=productionfür main-Branch,stagingfürstaging-Branch,previewsonst- Files:
.github/workflows/ci.yml,.gitea/workflows/ci.yml - Commit:
02-observability/sentry-ci: wire release jobs into ci workflows
- Nach API-Build:
-
Secrets dokumentieren —
docs/observability/sentry-selfhost.mderweitern 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
- Wie man in Sentry-UI einen Auth-Token erstellt (Settings → Account → API → Auth Tokens, Scope
-
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
- Release
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.ymlder auf einem Throwaway-Branch läuft und nur den Sentry-Step ausführt — manuell triggerbar viaworkflow_dispatch
- Test-Workflow
- E2E (Staging-CI):
- Tatsächlicher Push auf
agent/phase-02-sentry-ci→ Release in Sentry-UI vorhanden
- Tatsächlicher Push auf
- 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.shexistiert, 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_URLin 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 testgrü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 alscontinue-on-error: truemarkiert 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_TOKENmuss minimal-scoped sein — nurproject:releases. NICHTorg:admin, NICHTmember: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 +xundecho "::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-Versionworkflow_callunterstü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-reviewernach Task-Completion
Staging-Deployment-Steps
- Secrets in GitHub + Gitea hinterlegen (siehe Step 5)
- Branch
agent/phase-02-sentry-cipushen → CI läuft durch - 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 - Sentry-UI öffnen:
https://sentry.<staging-domain>/<org>/boilerplate-web/releases/<git-sha>/- Artifacts-Tab: > 0 Files
- Commits-Tab: > 0 Commits
- Künstlicher Error auf Web (
/__test/client-throw) → Issue zeigt "First Seen In Release: " mit unminifiziertem Stack-Trace - 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.mdA5 verifiesSENTRY_AUTH_TOKENis live on all three apps and the Gitea secret is set. That closes the stale token/env caveat and matchesPROGRESS.mdstatuscompletedfor #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-pendingstatus 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.)