Add multi-project Sentry/GlitchTip incident bridge with Gitea issue linking and release sync #612

New Issue

2026-07-09T18:46:50-05:00

jcwalker3 commented

2026-07-09 18:46:50 -05:00

Problem

The project needs observability incidents from Sentry or GlitchTip to become durable Gitea work automatically. When an error occurs, the bridge should create or update the correct Gitea issue, link the monitoring incident to the issue/PR, and update Sentry/GlitchTip when the fix is merged or released. This must work across multiple projects, not only Gitea-Tools.

Goal

Build a provider-neutral observability bridge for Sentry and GlitchTip. The bridge maps monitoring projects to Gitea repos, creates or updates Gitea issues from incidents, tracks links between incidents and Gitea work, and syncs resolution status back to the monitoring provider when work is released.

Design principle

Gitea owns work.
Sentry/GlitchTip owns incidents.
The bridge keeps them linked.
The allocator sees linked incidents as assignable work.
No monitoring provider may bypass Gitea workflow gates.

Configuration

Support multiple project mappings:

provider: sentry or glitchtip
monitor_base_url
monitor_org
monitor_project
gitea_org
gitea_repo
default labels
environment filters
severity thresholds
issue creation policy
release/resolution policy

Example:

projects:
  - name: gitea-tools-mcp
    provider: sentry
    monitor_base_url: https://sentry.prgs.cc
    monitor_org: prgs
    monitor_project: gitea-tools-mcp
    gitea_org: Scaled-Tech-Consulting
    gitea_repo: Gitea-Tools
    default_labels:
      - type:bug
      - observability
      - sentry
      - status:ready

Required provider adapters

1. Sentry adapter

list issues
get issue details
list issue events
update issue status when fixed/released if configured
support self-hosted base URL such as https://sentry.prgs.cc

2. GlitchTip adapter

list issues/incidents supported by deployed GlitchTip API
get issue details/events where supported
update status where supported
document any API differences from Sentry
support self-hosted GlitchTip base URL

Required MCP tools

gitea_observability_list_projects
gitea_observability_list_incidents
gitea_observability_get_incident
gitea_observability_reconcile_incident
gitea_observability_link_issue
gitea_observability_mark_fix_in_progress
gitea_observability_mark_released
gitea_observability_sync_resolution
gitea_observability_watchdog

Gitea issue creation behavior

For a new actionable incident:

Determine mapped Gitea repo.
Deduplicate against existing linked Gitea issues.
Create a Gitea issue if none exists.
Add labels based on provider, project, environment, severity, component, and status.
Include sanitized incident summary:
- provider
- provider issue ID
- provider issue URL
- project
- environment
- first_seen
- last_seen
- event count
- level/severity
- culprit/transaction
- affected release
- sanitized tags
- sanitized latest event summary
- canonical next action
Store durable link between monitoring incident and Gitea issue.

Update behavior

If the incident recurs, update the linked Gitea issue with recurrence data.
If the linked Gitea issue is closed but the incident reopens, create a recurrence comment or reopen according to policy.
If a PR is opened, mark incident as fix-in-progress where supported.
If a PR is merged, mark incident as pending release or resolved-in-next-release where supported.
If a release is deployed, mark incident resolved where supported.
If monitoring provider writeback is unsupported, record the limitation in Gitea and keep the local mapping.

Required storage

Maintain a durable mapping:

provider
provider_base_url
provider_org
provider_project
provider_issue_id
provider_short_id
provider_permalink
gitea_org
gitea_repo
gitea_issue_number
linked_pr_numbers
fingerprint
first_seen
last_seen
event_count
status
release_resolved_at
last_sync_at

Security/redaction

No tokens, passwords, cookies, auth headers, keychain IDs, private config contents, raw session-state files, or full prompt bodies.
Sanitize stack locals and request data.
Store only safe tags/context.
Provider API tokens must come from environment or secret store only.
Logs must not print provider tokens or DSNs.

Non-goals

Do not let Sentry/GlitchTip directly approve, merge, close, release, or mutate Gitea workflow state outside sanctioned tools.
Do not replace Gitea as the durable work record.
Do not assume GlitchTip writeback API equals Sentry API without verification.
Do not create duplicate Gitea issues for the same provider incident.

Acceptance criteria

One bridge config can map multiple monitoring projects to multiple Gitea repos.
Sentry self-hosted projects at https://sentry.prgs.cc can be scanned and reconciled.
GlitchTip projects can be scanned through a separate adapter with documented API differences.
New actionable incidents create exactly one linked Gitea issue.
Recurring incidents update the existing linked issue, not create duplicates.
Gitea issues include provider URL, provider issue ID, event count, first_seen, last_seen, environment, severity, affected release, and canonical next action.
PR-open, PR-merged, and release-deployed states can sync back to the provider where supported.
If provider writeback fails or is unsupported, Gitea records the failure and remains the source of truth.
Redaction tests prove secrets and sensitive request/session data are not stored or posted.
Tests cover multi-project mapping, dedupe, recurrence, closed issue recurrence, provider unavailable, missing token, Sentry adapter, GlitchTip adapter, and release sync.
Allocator can see observability-linked Gitea issues as normal work items.
Documentation explains setup for Sentry, GlitchTip, project mappings, tokens, labels, and release policies.

## Problem The project needs observability incidents from Sentry or GlitchTip to become durable Gitea work automatically. When an error occurs, the bridge should create or update the correct Gitea issue, link the monitoring incident to the issue/PR, and update Sentry/GlitchTip when the fix is merged or released. This must work across multiple projects, not only Gitea-Tools. ## Goal Build a provider-neutral observability bridge for Sentry and GlitchTip. The bridge maps monitoring projects to Gitea repos, creates or updates Gitea issues from incidents, tracks links between incidents and Gitea work, and syncs resolution status back to the monitoring provider when work is released. ## Design principle * Gitea owns work. * Sentry/GlitchTip owns incidents. * The bridge keeps them linked. * The allocator sees linked incidents as assignable work. * No monitoring provider may bypass Gitea workflow gates. ## Configuration Support multiple project mappings: * provider: sentry or glitchtip * monitor_base_url * monitor_org * monitor_project * gitea_org * gitea_repo * default labels * environment filters * severity thresholds * issue creation policy * release/resolution policy Example: ```yaml projects: - name: gitea-tools-mcp provider: sentry monitor_base_url: https://sentry.prgs.cc monitor_org: prgs monitor_project: gitea-tools-mcp gitea_org: Scaled-Tech-Consulting gitea_repo: Gitea-Tools default_labels: - type:bug - observability - sentry - status:ready ``` ## Required provider adapters ### 1. Sentry adapter * list issues * get issue details * list issue events * update issue status when fixed/released if configured * support self-hosted base URL such as `https://sentry.prgs.cc` ### 2. GlitchTip adapter * list issues/incidents supported by deployed GlitchTip API * get issue details/events where supported * update status where supported * document any API differences from Sentry * support self-hosted GlitchTip base URL ## Required MCP tools * `gitea_observability_list_projects` * `gitea_observability_list_incidents` * `gitea_observability_get_incident` * `gitea_observability_reconcile_incident` * `gitea_observability_link_issue` * `gitea_observability_mark_fix_in_progress` * `gitea_observability_mark_released` * `gitea_observability_sync_resolution` * `gitea_observability_watchdog` ## Gitea issue creation behavior For a new actionable incident: 1. Determine mapped Gitea repo. 2. Deduplicate against existing linked Gitea issues. 3. Create a Gitea issue if none exists. 4. Add labels based on provider, project, environment, severity, component, and status. 5. Include sanitized incident summary: * provider * provider issue ID * provider issue URL * project * environment * first_seen * last_seen * event count * level/severity * culprit/transaction * affected release * sanitized tags * sanitized latest event summary * canonical next action 6. Store durable link between monitoring incident and Gitea issue. ## Update behavior * If the incident recurs, update the linked Gitea issue with recurrence data. * If the linked Gitea issue is closed but the incident reopens, create a recurrence comment or reopen according to policy. * If a PR is opened, mark incident as fix-in-progress where supported. * If a PR is merged, mark incident as pending release or resolved-in-next-release where supported. * If a release is deployed, mark incident resolved where supported. * If monitoring provider writeback is unsupported, record the limitation in Gitea and keep the local mapping. ## Required storage Maintain a durable mapping: * provider * provider_base_url * provider_org * provider_project * provider_issue_id * provider_short_id * provider_permalink * gitea_org * gitea_repo * gitea_issue_number * linked_pr_numbers * fingerprint * first_seen * last_seen * event_count * status * release_resolved_at * last_sync_at ## Security/redaction * No tokens, passwords, cookies, auth headers, keychain IDs, private config contents, raw session-state files, or full prompt bodies. * Sanitize stack locals and request data. * Store only safe tags/context. * Provider API tokens must come from environment or secret store only. * Logs must not print provider tokens or DSNs. ## Non-goals * Do not let Sentry/GlitchTip directly approve, merge, close, release, or mutate Gitea workflow state outside sanctioned tools. * Do not replace Gitea as the durable work record. * Do not assume GlitchTip writeback API equals Sentry API without verification. * Do not create duplicate Gitea issues for the same provider incident. ## Acceptance criteria 1. One bridge config can map multiple monitoring projects to multiple Gitea repos. 2. Sentry self-hosted projects at `https://sentry.prgs.cc` can be scanned and reconciled. 3. GlitchTip projects can be scanned through a separate adapter with documented API differences. 4. New actionable incidents create exactly one linked Gitea issue. 5. Recurring incidents update the existing linked issue, not create duplicates. 6. Gitea issues include provider URL, provider issue ID, event count, first_seen, last_seen, environment, severity, affected release, and canonical next action. 7. PR-open, PR-merged, and release-deployed states can sync back to the provider where supported. 8. If provider writeback fails or is unsupported, Gitea records the failure and remains the source of truth. 9. Redaction tests prove secrets and sensitive request/session data are not stored or posted. 10. Tests cover multi-project mapping, dedupe, recurrence, closed issue recurrence, provider unavailable, missing token, Sentry adapter, GlitchTip adapter, and release sync. 11. Allocator can see observability-linked Gitea issues as normal work items. 12. Documentation explains setup for Sentry, GlitchTip, project mappings, tokens, labels, and release policies.

jcwalker3 added the glitchtip type:feature status:ready allocator observability sentry incident-bridge workflow-hardening multi-project labels 2026-07-09 18:46:52 -05:00

Add multi-project Sentry/GlitchTip incident bridge with Gitea issue linking and release sync #612