# 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`.