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.

4.1 KiB Raw Blame History