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.