diff --git a/docs/architecture/glitchtip-to-gitea-workflow-design.md b/docs/architecture/glitchtip-to-gitea-workflow-design.md new file mode 100644 index 0000000..08e4571 --- /dev/null +++ b/docs/architecture/glitchtip-to-gitea-workflow-design.md @@ -0,0 +1,56 @@ +# GlitchTip-to-Gitea Issue Filing Workflow Design + +- **Status:** Design (no implementation in this repo) +- **Issue:** #74 (parent umbrella: #75) +- **Related:** #78 (deduplication design, child of #74) +- **Date:** 2026-07-02 + +## 1. Boundary and Orchestration + +* **GlitchTip-to-Gitea filing is NOT a GlitchTip MCP capability.** The `glitchtip-mcp` boundary remains strictly read-only per ADR-0001. +* The filing capability lives in an **orchestrator / runbook / release workflow**. It **composes** separate GlitchTip **read** tools (from the `glitchtip-mcp` server) and Gitea **issue** tools (from the `gitea-mcp` server). +* The orchestrator **must not centralize credentials** into a single server. The GlitchTip MCP holds only GlitchTip tokens, and the Gitea MCP holds only Gitea tokens. + +## 2. Invocation and Safety + +* **Explicit invocation only:** There is no automatic, unsupervised filing in phase 1. A human or an explicitly-triggered automation must initiate the workflow. +* **Dry-run / Preview required:** The orchestrator must present a preview of the drafted Gitea issue (title, body, labels) and obtain explicit confirmation before calling the Gitea mutation tool to file the issue. +* **Gitea Profile Checks & Audit Logging:** The actual Gitea issue creation relies on `gitea-mcp`, and therefore inherently subjects the mutation to Gitea profile checks and audit logging as standard. + +## 3. Gitea Issue Format + +The workflow generates a Gitea issue using the following format and fields: + +### Required Fields +The issue body MUST include the following extracted fields from GlitchTip: +- **Project** +- **Environment** +- **Release** +- **First seen / Last seen** +- **Event count / User count** +- **Stack summary** (Truncated/summarized, no raw frames) +- **GlitchTip URL / linkback:** A permalink back to the GlitchTip web UI so users can view the full unredacted data securely. + +### Title Format +`[GlitchTip] {Project} - {Error Type}: {Short Message}` + +### Labels +The orchestrator must apply the following labels upon creation: +* `source:glitchtip` +* `bug` +* `status:triage` + +## 4. Redaction Rules + +To prevent PII or secret leakage into Gitea, the orchestrator and the underlying `glitchtip-mcp` read tools strictly omit and redact the following from the Gitea issue body: +* Request bodies +* Cookies and headers +* Authentication tokens / Session IDs +* PII (User emails, usernames, IPs) +* Full raw stack traces (source code lines) + +The principle is: **"Link, don't dump"**. The generated issue acts as an alert/pointer, while the raw context remains protected inside GlitchTip. + +## 5. Deduplication and Linking (Deferred) + +Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip issue IDs, and race condition handling) is specifically handled by **Issue #78** and will augment this design.