87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
# GlitchTip-to-Gitea Issue Filing Workflow Contract
|
|
|
|
- **Status:** Contract for the library-only implementation in
|
|
`Scaled-Tech-Consulting/mcp-control-plane` (#57)
|
|
- **Issue:** #153 (supersedes #74/#78 as the Gitea-Tools tracker)
|
|
- **Related:** #78 (deduplication design, child of #74)
|
|
- **Date:** 2026-07-07
|
|
|
|
## 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 a **library-only orchestrator** in
|
|
`mcp-control-plane` and is not exposed through `glitchtip-mcp`.
|
|
* The orchestrator composes the real GlitchTip read path with Gitea
|
|
issue-write tools. It must not use mocked GlitchTip issue data in production
|
|
filing paths.
|
|
* 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.
|
|
* If a future MCP surface exposes filing, it must be a separate write-boundary
|
|
server/profile with explicit Gitea issue-write permission and the same audit
|
|
gates. It must not be added to the read-only `glitchtip-mcp` surface.
|
|
|
|
## 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 must pass Gitea profile checks and
|
|
fail-closed mutation audit before create/link/comment actions.
|
|
* **Deduplication before create:** The orchestrator must run the
|
|
GlitchTip-to-Gitea dedup/linking logic before any Gitea create action. Create,
|
|
link, and skip decisions must be represented in tests.
|
|
|
|
## 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
|
|
|
|
Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip
|
|
issue IDs, and race condition handling) is integrated into the library-only
|
|
filing orchestrator in `mcp-control-plane`. The orchestrator must reuse that
|
|
dedup/linking path instead of duplicating or bypassing it.
|
|
|
|
## 6. Gitea-Tools Acceptance Contract for #153
|
|
|
|
Gitea-Tools does not host the filing implementation. This repository owns the
|
|
operator-facing contract:
|
|
|
|
* `glitchtip-mcp` remains read-only and exposes only GlitchTip inspection tools.
|
|
* Filing is implemented in `mcp-control-plane`, not in this Gitea MCP runtime.
|
|
* Filing uses the real GlitchTip read path, not mocked issue data.
|
|
* Dedup runs before any Gitea create action.
|
|
* Create/link/skip decisions and audit failure are covered by orchestrator tests.
|
|
* Mutation audit fails closed before any Gitea create, link, or comment mutation.
|
|
* Any future MCP exposure requires a separate write-boundary server/profile and
|
|
must not add Gitea write credentials to `glitchtip-mcp`.
|