Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 sysadmin
|
df840855cf |
@@ -1,41 +0,0 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [v1.1.0] - 2026-07-02
|
||||
|
||||
### Added
|
||||
- Read-only identity and eligibility tooling: `gitea_whoami` authenticated-user lookup (#11), `gitea_get_profile` runtime-profile discovery (#13), and `gitea_check_pr_eligibility` fail-closed PR eligibility checks (#14).
|
||||
- Identity lookup aliases (`gitea_get_authenticated_user` and `gitea_get_current_user`) for common MCP/LLM tool discovery (#9).
|
||||
- Gated PR review actions (`gitea_submit_pr_review`) reusing the eligibility gates (#15).
|
||||
- Gated PR merge workflow (`gitea_merge_pr`) with explicit `MERGE PR <n>` confirmation, head-SHA and changed-file pinning, and self-merge blocking as the only merge path (#16).
|
||||
- Task-scoped Gitea MCP execution profiles: documented profile model (#12) and runtime profiles via environment config with `allowed_operations` (#19).
|
||||
- Audit logging for all mutating MCP actions with execution-profile metadata and secret redaction (#18).
|
||||
- Shared API pagination (`api_get_all`) and hardened failure handling in `gitea_auth.api_request`: request timeouts, clear network/DNS errors, explicit 502/503/504 upstream errors, malformed-JSON handling, and redacted error text (#67).
|
||||
- `scripts/release-tag` SemVer-gated annotated-tag helper (safe-by-default, master-only, tests required) (#50).
|
||||
- Automatic `status:in-progress` release on issue close and PR close/merge (#56, #58).
|
||||
- `LLM-Agent-SHA` opaque agent attribution convention (Phase 0): documentation, handoff/review templates, and negative tests proving the SHA can never bypass self-review/self-merge gates (#86).
|
||||
- macOS `com.apple.provenance` cleanup helper tool and documentation (#3).
|
||||
- `manage_labels.py` refactored into reusable modes (`--create-labels`, `--apply-mapping`, `--add-label`) (#6).
|
||||
|
||||
### Changed
|
||||
- HTTP 429 responses now honor `Retry-After` with jittered exponential backoff (#27).
|
||||
- Read-only list tools (`gitea_list_issues`, `gitea_list_prs`, `gitea_list_labels`) now paginate across pages with bounded page caps (#67).
|
||||
- Automatic `status:in-progress` cleanup on issue/PR close and merge.
|
||||
- Label cleanup now utilizes safe targeted label deletion behavior rather than replacing the entire label set.
|
||||
|
||||
### Documentation
|
||||
- MCP security model and trust-boundary documentation (#8).
|
||||
- Developer testing guidelines (#70).
|
||||
- Jenkins read-only build-status tools design (#72).
|
||||
- Jenkins repo/branch/PR → job mapping design (#77).
|
||||
- Safety and boundary docs updated for Jenkins/GlitchTip: `glitchtip-mcp` boundary, read-only-first policy, mutation gating (#79).
|
||||
- Proposed label taxonomy for Jenkins/GlitchTip workflows (#80).
|
||||
- GlitchTip read-only error/event tools design (#73).
|
||||
- Multi-service MCP profile model extension (#76).
|
||||
|
||||
## [v1.0.1]
|
||||
- Fix Recent Timesheets Remove button text clipping and copy theme/whats_new in build.
|
||||
|
||||
## [v1.0.0]
|
||||
- Initial versioned release.
|
||||
@@ -1,59 +0,0 @@
|
||||
# GlitchTip-Gitea Deduplication and Linking Design
|
||||
|
||||
- **Status:** Design (child of #74)
|
||||
- **Issue:** #78 (parent: #74 / #75)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Overview and Goals
|
||||
To prevent automated error-reporting from flooding the Gitea issue tracker with duplicate tickets for the same underlying GlitchTip error, the filing orchestrator must deduplicate reports. Every filed Gitea issue will be cleanly linked back to its originating GlitchTip error via structured metadata.
|
||||
|
||||
## 2. Structured Metadata Marker
|
||||
Each Gitea issue filed by the orchestrator will contain a machine-readable, structured metadata block in its body. This metadata will contain the GlitchTip issue ID and fingerprint.
|
||||
|
||||
We will use a hidden HTML comment at the end of the issue body:
|
||||
```markdown
|
||||
<!-- glitchtip-metadata: {"issue_id": "12345", "fingerprint": "abc123xyz"} -->
|
||||
```
|
||||
|
||||
Adding this as a hidden comment allows orchestrators to parse the metadata reliably without cluttering the user interface or affecting human readability.
|
||||
|
||||
## 3. Search and Duplicate Detection Strategy
|
||||
Before the orchestrator files a new issue, it must search the target Gitea repository for any existing issues referencing the same GlitchTip error.
|
||||
|
||||
### Search Process:
|
||||
1. **API Query:** Query the Gitea repository's issues endpoint using the search term `"glitchtip-metadata"`. This narrows the results down to issues filed by this workflow. The query must search **both open and closed** issues (using Gitea API `state=all`).
|
||||
2. **Client-side Parsing:** Fetch the details/body of matching issues and extract the metadata block.
|
||||
3. **Identity Match:** Check if the Gitea issue's `issue_id` or `fingerprint` matches the incoming GlitchTip error. If a match is found, it is flagged as a duplicate.
|
||||
|
||||
## 4. Handling Closed Matching Issues (Open Owner Decision)
|
||||
When a matching duplicate Gitea issue is found but its status is **closed**, the workflow cannot assume a single correct behavior (e.g. reopening could cause infinite loops on flaky errors; creating new issues could cause duplicate spam).
|
||||
|
||||
The orchestrator must support configurable modes for this scenario:
|
||||
* Mode A: **Ask Human** (Prompt for decision: reopen, file new, or ignore) - *Default Mode*.
|
||||
* Mode B: **Comment-Only** (Post a comment in the closed Gitea issue noting that the error recurred, rather than reopening it).
|
||||
* Mode C: **Reopen** (Reopen the closed Gitea issue and apply `status:triage` / `status:in-progress`).
|
||||
* Mode D: **Create New** (Ignore the closed issue and file a new one, linking it to the previous closed issue).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Open Owner Decision:** The final default behavior and Mode configuration must be confirmed by the owner prior to implementation.
|
||||
|
||||
## 5. Concurrency and Race Condition Mitigation
|
||||
Since multiple runs of the orchestrator could occur concurrently (e.g. parallel Jenkins builds or multiple webhook deliveries), there is a risk of two runs checking for duplicates simultaneously and both creating new issues.
|
||||
|
||||
### Mitigation Strategies:
|
||||
1. **Single-Concurrency Gate:** Limit execution of the issue filing runbook to a single-concurrency queue (e.g. GHA `concurrency` groups, Jenkins lockable resources).
|
||||
2. **Double-Check Query:** Add a randomized delay/jitter (0-5 seconds) before creating the issue, and perform a final check of Gitea issues immediately prior to POSTing the new issue.
|
||||
3. **Idempotency Header / Cache:** (Optional) Keep a lightweight, short-lived external state store or cache if a persistent runner is used.
|
||||
|
||||
## 6. Spam Prevention (Spam Cap)
|
||||
To protect Gitea from an unexpected surge in errors (e.g., during a major site outage), the orchestrator must enforce a maximum spam cap per execution:
|
||||
- **Default Cap:** Maximum of 5 new Gitea issues filed per execution run.
|
||||
- **Exceeded Behavior:** If the cap is reached, the runbook will halt filing new issues, log a warning, and print a summary of all skipped issues to the console/audit logs.
|
||||
|
||||
## 7. Testing Strategy (Mocked Verification)
|
||||
Unit tests for the implementing orchestrator must use mocked Gitea/GlitchTip APIs to assert:
|
||||
1. **Deduplication:** A second run with a matching fingerprint does not trigger issue creation.
|
||||
2. **State Search:** Both open and closed issues are queried (`state=all`).
|
||||
3. **Closed Match mode:** Mode logic operates as configured (`comment`, `reopen`, `new`, `ask`).
|
||||
4. **Spam Cap:** Asserts that only the capped limit of issues is created, even if more errors are fetched from GlitchTip.
|
||||
5. **No Secrets/PII Leak:** Check that metadata and issue content are clean of credentials.
|
||||
@@ -1,174 +0,0 @@
|
||||
# GlitchTip Read-Only Error/Event Tools — Design Notes
|
||||
|
||||
- **Status:** Design (implementation-ready notes; **no implementation in this repo**)
|
||||
- **Issue:** #73 (umbrella: #75; boundary decision: ADR-0001, #71)
|
||||
- **Related:** #74 (GlitchTip→Gitea filing workflow — composes these read tools),
|
||||
#78 (dedup/linking, child of #74), #76 (per-service profile schema)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Purpose and scope
|
||||
|
||||
Define the minimum **read-only** GlitchTip MCP tool set that lets an LLM answer:
|
||||
*"What unresolved errors does project X have (by environment/release), and what
|
||||
is this specific error?"* — with privacy-safe output suitable for LLM context,
|
||||
issue bodies, and audit logs.
|
||||
|
||||
Strictly read-only, per ADR-0001:
|
||||
|
||||
- **No mutation tools** — no resolving/ignoring/assigning issues, no comment
|
||||
posting, no project/team/key administration, no deletes.
|
||||
- **No automatic GlitchTip→Gitea filing** (that is #74's *orchestrated,
|
||||
explicitly-invoked* workflow; it composes these read tools and Gitea write
|
||||
tools — never one dual-credential server).
|
||||
- **This server never holds Gitea write credentials.**
|
||||
|
||||
## 2. Boundary placement (namespace pending)
|
||||
|
||||
These tools belong to the GlitchTip observability boundary of the MCP Control
|
||||
Plane — `glitchtip-mcp` (ADR-0001's recommendation), `observability-mcp`, or
|
||||
folded into `ops-mcp`. **ADR-0001 open owner decision #2 picks the name; this
|
||||
design does not assume it.** Tool names below use the `glitchtip_` prefix for
|
||||
readability and rename mechanically with the decision.
|
||||
|
||||
Fixed regardless of the name (per `tool-boundaries.md`,
|
||||
`credential-isolation.md`):
|
||||
|
||||
- Own server process, own `.env`, GlitchTip credentials only.
|
||||
- No Gitea, Jenkins, or Ops tokens in this runtime; no GlitchTip token
|
||||
anywhere else.
|
||||
|
||||
## 3. API surface note (Sentry compatibility)
|
||||
|
||||
GlitchTip implements a Sentry-compatible REST API (`/api/0/...` — organizations,
|
||||
projects, issues, events). The design targets **GlitchTip's documented subset**
|
||||
only; Sentry-only endpoints must not be assumed. The implementation should pin
|
||||
against a tested GlitchTip version and treat missing endpoints/fields as
|
||||
degraded-but-safe (omit field, never crash).
|
||||
|
||||
## 4. Minimum read-only tool set
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| `glitchtip_whoami` | Verify authenticated identity + active profile (mirror of `gitea_whoami`; fail-closed identity proof) |
|
||||
| `glitchtip_list_projects` | Projects visible to the token (org-scoped), with pagination bounds |
|
||||
| `glitchtip_list_unresolved` | Unresolved issues for a project, filterable (§6), sorted by last-seen |
|
||||
| `glitchtip_get_issue` | Safe detail of one issue (fields §5) |
|
||||
| `glitchtip_recent_events` | Recent events for an issue (summaries only, §5) |
|
||||
| `glitchtip_search` | Issue search within a project (query + filters §6) |
|
||||
|
||||
All tools are `GET`-only. No tool issues PUT/POST/DELETE.
|
||||
|
||||
## 5. Privacy: field-level allowlist (the core rule)
|
||||
|
||||
Error events routinely contain PII and secrets (request bodies, cookies,
|
||||
headers, tokens, user emails/IPs, local variables). Therefore: **allowlist
|
||||
projection only — raw event/issue payloads are never passed through.**
|
||||
|
||||
### Issue-level safe fields (`glitchtip_list_unresolved`, `glitchtip_get_issue`, `glitchtip_search`)
|
||||
|
||||
| Field | Notes |
|
||||
|---|---|
|
||||
| `issue_id` | GlitchTip issue ID (dedup key for #78) |
|
||||
| `fingerprint` | When available (dedup key for #78) |
|
||||
| `title` / `culprit` | Error type + short message/transaction — redactor-passed |
|
||||
| `project` | Slug |
|
||||
| `level` | error/warning/… |
|
||||
| `status` | unresolved/… |
|
||||
| `environment` | When filtered/available |
|
||||
| `release` | Version string |
|
||||
| `first_seen` / `last_seen` | ISO-8601 UTC |
|
||||
| `event_count` / `user_count` | Numbers only — never user identities |
|
||||
| `permalink` | GlitchTip web URL (the "link, not dump" principle) |
|
||||
|
||||
### Event-level safe fields (`glitchtip_recent_events`)
|
||||
|
||||
`event_id`, `timestamp`, `level`, `environment`, `release`, redactor-passed
|
||||
`message`, and a **stack summary** only: top N (default 5) frames as
|
||||
`module/filename:function:line` — in-app frames preferred.
|
||||
|
||||
### Redact / omit — never returned
|
||||
|
||||
Request headers; cookies; auth/session fields; user emails, usernames, IPs;
|
||||
request/form bodies; query strings; local variables; full raw stack frames
|
||||
(source context lines); SDK/device metadata beyond platform name; breadcrumbs;
|
||||
any `extra`/`context` blobs.
|
||||
|
||||
Full raw frames or request context require a **separate, explicitly approved**
|
||||
operation (`glitchtip.event.read_raw`) that is absent from default profiles —
|
||||
same pattern as `jenkins.console.read` in the #72 design. Even then, output
|
||||
passes the shared secret redactor; redaction failure ⇒ error, never raw text.
|
||||
|
||||
**Default output = fingerprint / release / summary + permalink.** The
|
||||
permalink carries the human to the full data in GlitchTip's own UI, where its
|
||||
access control applies — the MCP layer does not re-serve raw payloads.
|
||||
|
||||
## 6. Filtering and pagination
|
||||
|
||||
Filters (all optional, combinable): `project` (required for issue/event
|
||||
queries), `environment`, `release`, `fingerprint`, free-text `query`
|
||||
(GlitchTip search syntax, e.g. `is:unresolved`).
|
||||
|
||||
Pagination: cursor-based per the API. Bounds: per-page cap 50; default overall
|
||||
cap 100 items; hard cap `max_pages` (default 10) against runaway loops —
|
||||
mirroring `gitea_auth.api_get_all`. Truncation is **explicit** in the return
|
||||
(`"truncated": true`) — never silent.
|
||||
|
||||
## 7. Credentials and profile requirements
|
||||
|
||||
Per-service profile model (`gitea-execution-profiles.md`, extended by #76):
|
||||
|
||||
- Env/config: `GLITCHTIP_URL`, `GLITCHTIP_ORG`, `GLITCHTIP_TOKEN_SOURCE_NAME`
|
||||
(secret **name** only; value resolved at runtime, never logged/committed).
|
||||
- Profile: e.g. `glitchtip-readonly` with namespaced
|
||||
`allowed_operations: ["glitchtip.read", "glitchtip.event.read"]`
|
||||
(+ `glitchtip.event.read_raw` only with explicit approval);
|
||||
`forbidden_operations: ["glitchtip.issue.mutate", "glitchtip.admin"]`
|
||||
belt-and-braces though no mutating tool exists.
|
||||
- Missing URL/org/token/profile ⇒ **fail closed** before any network call.
|
||||
- Read-only ⇒ no confirmation gates; identity (`glitchtip_whoami`) must work so
|
||||
workflows can prove which account they read as.
|
||||
|
||||
## 8. Failure behavior (fail closed, clear, safe)
|
||||
|
||||
| Condition | Behavior |
|
||||
|---|---|
|
||||
| Unknown project/issue | Explicit `{"found": false, ...}` — no fuzzy matching |
|
||||
| GlitchTip unreachable (DNS/timeout) | `"network error contacting GlitchTip: <redacted reason>"` — mirror `gitea_auth.api_request` conversion |
|
||||
| 502/503/504 | "GlitchTip upstream unavailable" |
|
||||
| 401/403 | "GlitchTip auth failed / insufficient permissions" — no credential echo |
|
||||
| 429 | Honor Retry-After with capped jittered backoff (as `gitea_auth`) |
|
||||
| Malformed JSON | "malformed JSON response from GlitchTip" — no raw-body dump |
|
||||
| Missing profile/creds | Fail closed before any network call (§7) |
|
||||
|
||||
All error text passes the shared secret redactor.
|
||||
|
||||
## 9. Testing strategy (mocked; for the implementing package)
|
||||
|
||||
Mocked-GlitchTip unit tests only, per `docs/developer-testing-guidelines.md`:
|
||||
|
||||
- Assert method is always `GET`; URL/filter/cursor shape correct.
|
||||
- **Projection tests:** response fixtures containing emails, IPs, cookies,
|
||||
headers, request bodies, locals, full frames ⇒ none appear in output
|
||||
(explicit negative assertions per §5's redact list).
|
||||
- Stack summary: top-N frame cap enforced; source-context lines absent.
|
||||
- Pagination: per-page/overall/max-pages caps; explicit `truncated` flag.
|
||||
- Filters: environment/release/fingerprint/query passed through correctly.
|
||||
- Failure matrix of §8 incl. no-token-in-error assertions.
|
||||
- Profile gate: missing/insufficient profile ⇒ no network call
|
||||
(`mock_api.assert_not_called()` pattern).
|
||||
- `read_raw` op absent ⇒ raw-frame request refused without an API call.
|
||||
|
||||
## 10. Implementation-readiness checklist
|
||||
|
||||
Ready to implement once:
|
||||
|
||||
1. ADR-0001 owner decision #2 (namespace/placement) is made — mechanical
|
||||
rename of the `glitchtip_` prefix if needed.
|
||||
2. ADR-0001 owner decision #1 (repo home) is made.
|
||||
3. #76 profile schema exists (or a minimal `glitchtip-readonly` profile is
|
||||
hand-rolled to the same rules).
|
||||
4. A pinned GlitchTip version is chosen for API-subset testing (§3).
|
||||
|
||||
Explicitly **not** unlocked by this document: any GlitchTip mutation, any
|
||||
automatic Gitea filing (#74 designs that as a gated, explicitly-invoked
|
||||
orchestrated workflow), any Gitea credentials in this boundary.
|
||||
@@ -1,56 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,165 +0,0 @@
|
||||
# Jenkins Repo/Branch/PR → Job Mapping — Design Notes
|
||||
|
||||
- **Status:** Design (implementation-ready notes; **no implementation in this repo**)
|
||||
- **Issue:** #77 (parent: #72 read-only tools design; umbrella: #75; boundary: ADR-0001, #71)
|
||||
- **Related docs:** [`jenkins-readonly-build-status-design.md`](jenkins-readonly-build-status-design.md)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
The #72 tool set addresses Jenkins jobs by **explicit fully-qualified job
|
||||
path**. This document designs the layer above it: how a *(repository, branch,
|
||||
PR)* tuple — the vocabulary of Gitea workflows — resolves deterministically to
|
||||
a Jenkins job path, so an LLM can ask "did the build for `Gitea-Tools`
|
||||
`master` pass?" without knowing Jenkins internals.
|
||||
|
||||
Hard constraints inherited from #72 / ADR-0001:
|
||||
|
||||
- **No silent guessing of job names.** Unmapped input returns an explicit
|
||||
"no mapping" result — never a fuzzy match, never a constructed-and-probed
|
||||
name.
|
||||
- **Read-only.** Mapping introduces no Jenkins write actions.
|
||||
- Lives in the **`jenkins-mcp`** boundary; no Gitea credentials involved.
|
||||
|
||||
## 2. Mapping format
|
||||
|
||||
Declarative, versioned config (TOML or JSON — match whatever config format
|
||||
`jenkins-mcp` adopts; illustrated here as TOML):
|
||||
|
||||
```toml
|
||||
version = 1
|
||||
|
||||
[[mapping]]
|
||||
# Source side (what the caller supplies)
|
||||
repo = "Scaled-Tech-Consulting/Gitea-Tools" # org/repo, exact
|
||||
# Target side (where it lives in Jenkins)
|
||||
job = "scaled-tech/gitea-tools" # foldered job path
|
||||
type = "multibranch" # "multibranch" | "single" | "parameterized-view"
|
||||
|
||||
[[mapping]]
|
||||
repo = "Scaled-Tech-Consulting/Timesheet"
|
||||
branch = "master" # optional: branch-specific override
|
||||
job = "scaled-tech/timesheet-master"
|
||||
type = "single"
|
||||
```
|
||||
|
||||
Field semantics:
|
||||
|
||||
| Field | Required | Meaning |
|
||||
|---|---|---|
|
||||
| `repo` | yes | Exact `org/repo` (case-insensitive compare, stored canonical) |
|
||||
| `branch` | no | Exact branch name this entry pins; absent = all branches |
|
||||
| `job` | yes | Fully-qualified Jenkins job path, folders `/`-joined |
|
||||
| `type` | yes | How branch/PR resolves under the job (§3) |
|
||||
|
||||
Rules:
|
||||
|
||||
- **Exact matching only** on `repo` and `branch`. No globs in v1 (globs invite
|
||||
accidental over-matching; add later behind an explicit `pattern = true` flag
|
||||
if ever needed).
|
||||
- Unknown `type` or malformed entry ⇒ config load fails closed with a clear
|
||||
error naming the entry — a broken mapping file must not half-load.
|
||||
- Duplicate `(repo, branch)` keys ⇒ load error (ambiguity is refused, not
|
||||
resolved).
|
||||
|
||||
## 3. Resolution semantics by job type
|
||||
|
||||
Given caller input `(repo, branch?, pr?)`:
|
||||
|
||||
- **`multibranch`** — branch job addressed as `<job>/<url-encoded-branch>`
|
||||
(e.g. `feature/x` → `feature%2Fx`). PRs addressed as `<job>/PR-<number>`
|
||||
(Jenkins multibranch PR-discovery naming). Both per #72 §8.
|
||||
- **`single`** — the job path is used as-is; `branch`/`pr` input beyond the
|
||||
entry's pinned branch is a **no-mapping** result (a single job cannot answer
|
||||
for arbitrary branches).
|
||||
- **`parameterized-view`** — read-only variant for jobs that encode branch as
|
||||
a build parameter: resolution returns the base job path plus a
|
||||
`branch_param` filter hint the status tools may apply client-side when
|
||||
scanning recent builds. It never triggers anything (read-only rule).
|
||||
|
||||
## 4. Precedence
|
||||
|
||||
Most-specific entry wins, evaluated in this order:
|
||||
|
||||
1. `(repo, branch)` exact entry — branch-pinned override.
|
||||
2. `(repo)` entry — repo-wide (multibranch typical).
|
||||
3. Nothing → **no mapping** (§5).
|
||||
|
||||
PR input resolves through the same chain: a PR belongs to its **base repo**'s
|
||||
mapping; forks never introduce their own mapping (a fork's head repo is not
|
||||
consulted — CI runs live under the base repo's job). If the base repo is
|
||||
unmapped, the PR is unmapped.
|
||||
|
||||
Ties are impossible by construction (duplicate keys refused at load).
|
||||
|
||||
## 5. No-match behavior
|
||||
|
||||
```json
|
||||
{
|
||||
"mapped": false,
|
||||
"repo": "org/unknown-repo",
|
||||
"branch": "master",
|
||||
"error": "no Jenkins job mapping for this repo/branch",
|
||||
"hint": "add an entry to the jenkins-mcp mapping config"
|
||||
}
|
||||
```
|
||||
|
||||
- Deterministic, explicit, machine-checkable (`mapped: false`).
|
||||
- **Never** falls back to name construction ("repo name probably equals job
|
||||
name"), never probes Jenkins for candidates, never string-similarity ranks.
|
||||
- The hint names the config, not a guessed job.
|
||||
|
||||
## 6. Where the mapping config lives
|
||||
|
||||
- **In the `jenkins-mcp` package/deployment** (e.g. `jenkins-mcp/mapping.toml`),
|
||||
version-controlled next to the server that consumes it — *not* in Gitea-Tools
|
||||
and *not* in per-user env vars (mappings are shared team facts, not
|
||||
credentials).
|
||||
- Path overridable via env (`JENKINS_MCP_MAPPING_FILE`) for tests/containers.
|
||||
- Contains **no secrets** — job paths and repo names only — so it is safe to
|
||||
commit and review like any other config.
|
||||
- Reloaded at server start; a hot-reload tool is out of scope (restart is the
|
||||
documented path).
|
||||
|
||||
## 7. Exposed tool surface (read-only)
|
||||
|
||||
One addition to the #72 tool set:
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| `jenkins_resolve_job` | `(repo, branch?, pr?)` → `{mapped, job, addressed_path, type}` or the §5 no-match result. Pure config lookup — **no Jenkins API call at all.** |
|
||||
|
||||
Status tools (`jenkins_latest_build` etc.) accept either an explicit job path
|
||||
(as designed in #72) **or** `(repo, branch)` which they resolve via the same
|
||||
mapping layer first. Resolution failure surfaces the §5 payload rather than
|
||||
querying Jenkins.
|
||||
|
||||
## 8. Testing strategy (mocked; for the implementing package)
|
||||
|
||||
Config-layer tests (no network at all):
|
||||
|
||||
- Exact-match hit: repo-wide and branch-pinned entries.
|
||||
- Precedence: branch-pinned beats repo-wide.
|
||||
- Multibranch encoding: `feature/x` → `<job>/feature%2Fx`; PR → `<job>/PR-7`.
|
||||
- `single` type with non-pinned branch ⇒ no-mapping.
|
||||
- Fork PR resolves through base repo; unmapped base ⇒ no-mapping.
|
||||
- Unknown repo/branch ⇒ §5 payload, and **no Jenkins client call**
|
||||
(`mock_api.assert_not_called()`).
|
||||
- Malformed config / duplicate keys / unknown type ⇒ load fails closed with
|
||||
entry-naming error.
|
||||
- No-secret check: mapping load/error paths never touch or print credentials.
|
||||
|
||||
Integration with mocked Jenkins API (per #72 §9): resolved path is used
|
||||
verbatim in the GET URL; no write verbs anywhere.
|
||||
|
||||
## 9. Standalone-worthiness and readiness
|
||||
|
||||
#77 was split from #72 on the condition it stays "standalone only if mapping
|
||||
is nontrivial." The precedence rules, fork/PR semantics, three job types, and
|
||||
fail-closed config loading above are the nontrivial part; this document is the
|
||||
justification.
|
||||
|
||||
Ready to implement in `jenkins-mcp` when #72's readiness checklist clears
|
||||
(ADR-0001 owner decision #1; profile schema per #76 or hand-rolled
|
||||
`jenkins-readonly`). Nothing here unlocks build triggers, deploys, or
|
||||
parameterized launches.
|
||||
@@ -1,151 +0,0 @@
|
||||
# Jenkins Read-Only Build Status Tools — Design Notes
|
||||
|
||||
- **Status:** Design (implementation-ready notes; **no implementation in this repo**)
|
||||
- **Issue:** #72 (parent umbrella: #75; boundary decision: ADR-0001, #71)
|
||||
- **Related:** #77 (repo/branch/PR → job mapping, designed separately)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Purpose and scope
|
||||
|
||||
Define the minimum **read-only** Jenkins MCP tool set that lets an LLM answer:
|
||||
*"Did the latest build for this project/branch succeed or fail?"* — plus enough
|
||||
detail (build URL, number, timing, result) to report or investigate.
|
||||
|
||||
Phase 1 is **strictly read-only**, per ADR-0001
|
||||
([`adr-0001-mcp-control-plane-boundaries.md`](adr-0001-mcp-control-plane-boundaries.md)):
|
||||
|
||||
- **Excluded: build triggers.**
|
||||
- **Excluded: deploy triggers.**
|
||||
- **Excluded: parameterized job launches.**
|
||||
- Excluded: job creation/deletion/config changes, queue manipulation, node
|
||||
management — any Jenkins mutation whatsoever.
|
||||
|
||||
## 2. Boundary placement
|
||||
|
||||
These tools belong to the **`jenkins-mcp`** package/server of the MCP Control
|
||||
Plane — **never** inside `gitea-mcp` (`mcp_server.py` in this repo).
|
||||
Consequences (from `tool-boundaries.md`, `credential-isolation.md`, ADR-0001):
|
||||
|
||||
- `jenkins-mcp` runs as its own server process with its own `.env`.
|
||||
- **Jenkins credentials never enter the Gitea MCP runtime**, and Gitea
|
||||
credentials never enter `jenkins-mcp`.
|
||||
- This document lands in this repo only because the repo currently hosts the
|
||||
Control Plane's architecture docs; the code ships elsewhere (owner decision
|
||||
#1 of ADR-0001).
|
||||
|
||||
## 3. Minimum read-only tool set
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| `jenkins_whoami` | Verify authenticated Jenkins identity + active profile (mirror of `gitea_whoami`; fail-closed identity proof before anything else) |
|
||||
| `jenkins_list_jobs` | List visible jobs (supports folder paths), with pagination bounds |
|
||||
| `jenkins_latest_build` | The primary question: latest build of a job (or job+branch for multibranch) → status summary |
|
||||
| `jenkins_build_status` | Status of a specific build number (job, number) |
|
||||
| `jenkins_get_build` | Full safe detail of a build (fields in §4) |
|
||||
| `jenkins_console_tail` | Bounded, redacted tail of a build's console log (§6) — optional, approval-gated addition |
|
||||
|
||||
All tools are `GET`-only against the Jenkins JSON API (`/api/json`,
|
||||
`.../lastBuild/api/json`, `.../consoleText`). No tool issues POST/PUT/DELETE.
|
||||
|
||||
## 4. Return payloads (safe fields)
|
||||
|
||||
`jenkins_latest_build` / `jenkins_build_status` / `jenkins_get_build` return:
|
||||
|
||||
| Field | Source | Notes |
|
||||
|---|---|---|
|
||||
| `job` | request | Fully-qualified job path (folders joined with `/`) |
|
||||
| `build_number` | `number` | int |
|
||||
| `result` | `result` | `SUCCESS` / `FAILURE` / `UNSTABLE` / `ABORTED` / `NOT_BUILT`; `null` → `IN_PROGRESS` when `building=true` |
|
||||
| `building` | `building` | bool |
|
||||
| `url` | `url` | Build URL |
|
||||
| `branch` | multibranch job name / SCM action | Best-effort; omitted when unknown |
|
||||
| `timestamp` | `timestamp` | ISO-8601 UTC (converted from epoch ms) |
|
||||
| `duration_seconds` | `duration` | 0/omitted while building |
|
||||
| `commit_sha` | SCM build action | Best-effort; omitted when unknown |
|
||||
|
||||
Rules: no raw Jenkins payload passthrough (allowlist projection only); no
|
||||
`Authorization` header, token, or crumb material in any output or error
|
||||
(reuse the shared redaction approach of `safety-model.md` §3 / `gitea_audit`).
|
||||
|
||||
## 5. Failure behavior (fail closed, clear, safe)
|
||||
|
||||
| Condition | Behavior |
|
||||
|---|---|
|
||||
| Unknown job | Explicit `{"found": false, "job": "<path>", "error": "job not found"}` — never guess or fuzzy-match a job name (hard rule; see also #77) |
|
||||
| Jenkins unreachable (DNS/timeout/conn refused) | Clear `"network error contacting Jenkins: <redacted reason>"`; no retry storm — mirror `gitea_auth.api_request` timeout + failure conversion |
|
||||
| 502/503/504 | Explicit "Jenkins upstream unavailable" |
|
||||
| 401/403 | "Jenkins auth failed / insufficient permissions" — **without** echoing credentials or the request's auth material |
|
||||
| Malformed JSON | "malformed JSON response from Jenkins" (no raw-body dump) |
|
||||
| Missing profile/creds | Fail closed before any network call (§7) |
|
||||
|
||||
## 6. Console tail safety (`jenkins_console_tail`)
|
||||
|
||||
Console logs are the highest-risk surface (secrets, tokens, internal hosts
|
||||
routinely leak into build logs). If included at all (owner may defer it):
|
||||
|
||||
- **Bounded:** hard server-side cap (default: last 200 lines AND ≤ 64 KiB,
|
||||
whichever is smaller; caller may request less, never more).
|
||||
- **Redacted:** pass through the shared secret redactor (token/`Basic`/`Bearer`/
|
||||
password/key-value patterns) before returning; redaction failure ⇒ return an
|
||||
error, never the raw text.
|
||||
- **Default off:** summary fields (`result`, failing stage if cheaply available)
|
||||
are preferred; the tail requires an explicit `allowed_operations` entry
|
||||
(`jenkins.console.read`) distinct from plain `jenkins.build.read`.
|
||||
|
||||
## 7. Credentials and profile requirements
|
||||
|
||||
Follows the per-service profile model (`gitea-execution-profiles.md`, extended
|
||||
by #76):
|
||||
|
||||
- Env/config: `JENKINS_URL`, `JENKINS_USER`, `JENKINS_TOKEN_SOURCE_NAME`
|
||||
(name-of-secret only — value resolved at runtime, never logged/committed).
|
||||
- Profile: e.g. `jenkins-readonly` with namespaced
|
||||
`allowed_operations: ["jenkins.read", "jenkins.build.read"]`
|
||||
(+ `jenkins.console.read` only if the tail tool is approved);
|
||||
`forbidden_operations: ["jenkins.build.trigger", "jenkins.deploy", "jenkins.job.configure"]`
|
||||
as belt-and-braces even though no mutating tool exists.
|
||||
- Missing URL/user/token/profile ⇒ **fail closed** with a clear message.
|
||||
- Since every tool is read-only, no confirmation gates are needed — but
|
||||
identity (`jenkins_whoami`) must still work so workflows can prove which
|
||||
Jenkins account they act as.
|
||||
|
||||
## 8. Job addressing and mapping
|
||||
|
||||
Tools accept an explicit fully-qualified job path (folder-aware:
|
||||
`folder/subfolder/job`). How a *repo/branch/PR* resolves to that job path is
|
||||
**out of scope here** and designed in **#77**, with these fixed constraints:
|
||||
|
||||
- No silent guessing of job names — unmapped input returns an explicit
|
||||
"no mapping" result.
|
||||
- Multibranch pipelines address a branch job as `<job>/<branch>` with proper
|
||||
URL-encoding of branch names (e.g. `feature%2Fx`).
|
||||
|
||||
## 9. Testing strategy (for the implementing package)
|
||||
|
||||
Mocked-Jenkins unit tests only (no live Jenkins in unit CI), mirroring this
|
||||
repo's conventions (`docs/developer-testing-guidelines.md`):
|
||||
|
||||
- Patch the HTTP client; assert method is always `GET` and URL shape is correct
|
||||
(folders, multibranch encoding).
|
||||
- Success projections: field allowlist exactly as §4; unknown fields dropped.
|
||||
- `result=null + building=true` ⇒ `IN_PROGRESS`.
|
||||
- Unknown job ⇒ found:false, no fuzzy match, no API retry.
|
||||
- Timeout/DNS/5xx/malformed-JSON ⇒ safe errors, no secret/credential leakage
|
||||
(explicit no-token-in-error assertions).
|
||||
- Console tail: cap enforcement (lines and bytes), redaction applied, redaction
|
||||
failure ⇒ error not raw text, gated behind `jenkins.console.read`.
|
||||
- Profile gate: missing/insufficient profile ⇒ no network call
|
||||
(`mock_api.assert_not_called()` pattern).
|
||||
|
||||
## 10. Implementation-readiness checklist
|
||||
|
||||
Ready to implement in `jenkins-mcp` once:
|
||||
|
||||
1. ADR-0001 owner decision #1 (where `jenkins-mcp` lives) is made.
|
||||
2. #76 profile schema exists (or a minimal `jenkins-readonly` profile is
|
||||
hand-rolled to the same rules).
|
||||
3. #77 mapping design is accepted (or tools ship path-addressed only, mapping
|
||||
deferred).
|
||||
|
||||
Explicitly **not** unlocked by this document: build triggers, deploys,
|
||||
parameterized launches, any Jenkins code in `mcp_server.py`.
|
||||
@@ -1,90 +0,0 @@
|
||||
# MCP Gitea Server Refactor: Compatibility Matrix & Staged Plan
|
||||
|
||||
- **Status:** Staging/Design (First phase of #65)
|
||||
- **Issue:** #65 (Staged refactor of `mcp_server.py` into a modular package)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Overview and Refactoring Contract
|
||||
The goal of this refactor is to split the monolith `mcp_server.py` (~1689 lines) into a clean, maintainable, and modular Python package (`gitea_tools`).
|
||||
|
||||
To ensure complete backward compatibility, we establish a strict contract:
|
||||
* **No functional changes:** Code behaviour, API endpoint targets, parameter sets, and return formats must remain identical.
|
||||
* **No gate bypasses:** Allowed operations, forbidden operations, identity resolving, and audit logging must continue to execute exactly as they do in the monolith.
|
||||
* **Independent testing:** The full pytest suite must pass with 100% success after every single stage.
|
||||
|
||||
---
|
||||
|
||||
## 2. Compatibility Matrix
|
||||
|
||||
The following table documents every MCP tool's expected signature, parameters, return payload shape, and error behavior that must be preserved.
|
||||
|
||||
### 2.1 Issue & Label Management Tools
|
||||
|
||||
| Tool Name | Parameters | Return Payload Shape | Error Behavior / Edge Cases |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `gitea_create_issue` | `title: str`, `body: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict containing issue details (`number`, `title`, `body`, `state`, `labels`, `assignee`, `url`) | Raises error on auth failure, missing parameters, or Gitea API validation error. |
|
||||
| `gitea_close_issue` | `issue_number: int`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict detailing the closed issue. | Raises 404 if issue doesn't exist; fails closed if user has insufficient permission. |
|
||||
| `gitea_list_issues` | `state: str`, `label: str \| None`, `limit: int`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | List of dicts representing matched issues. | Limits pagination per page and overall maximum caps. |
|
||||
| `gitea_view_issue` | `issue_number: int`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of detailed issue attributes. | Returns clear 404 error if not found. |
|
||||
| `gitea_mark_issue` | `issue_number: int`, `action: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict indicating current label states (presence of `status:in-progress`). | Rejects unknown actions; fails if label doesn't exist on Gitea. |
|
||||
| `gitea_list_labels` | `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | List of dicts representing labels. | Basic auth error fallback behavior. |
|
||||
| `gitea_create_label` | `name: str`, `color: str`, `description: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of created label properties. | Fails on duplicate names or invalid color hex formats. |
|
||||
| `gitea_set_issue_labels` | `issue_number: int`, `labels: list[str]`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | List of all labels currently applied to the issue. | Fails closed if any label name does not exist. |
|
||||
|
||||
### 2.2 PR & Review Management Tools
|
||||
|
||||
| Tool Name | Parameters | Return Payload Shape | Error Behavior / Edge Cases |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `gitea_create_pr` | `title: str`, `head: str`, `base: str`, `body: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict detailing the created PR. | Fails on missing branches, existing duplicate PR, or invalid base branch. |
|
||||
| `gitea_list_prs` | `state: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | List of dicts representing open/closed PRs. | Standard limits apply. |
|
||||
| `gitea_view_pr` | `pr_number: int`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of detailed PR attributes. | Fails if PR does not exist. |
|
||||
| `gitea_check_pr_eligibility` | `pr_number: int`, `action: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict: `{"eligible": bool, "reasons": list[str]}` | Non-gated, safe, read-only. Fails on invalid actions. |
|
||||
| `gitea_submit_pr_review` | `pr_number: int`, `action: str`, `body: str`, `expected_head_sha: str \| None`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of submitted review properties. | Rejects self-review; fails if head SHA has changed in the meantime. |
|
||||
| `gitea_edit_pr` | `pr_number: int`, `title: str \| None`, `body: str \| None`, `state: str \| None`, `base: str \| None`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of updated PR attributes. | Fails on invalid fields or if PR state transition is blocked. |
|
||||
| `gitea_merge_pr` | `pr_number: int`, `confirmation: str`, `expected_head_sha: str \| None`, `expected_changed_files: list[str] \| None`, `do: str`, `title: str \| None`, `message: str \| None`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict of merge result details. | Fails if any gating eligibility checks fail (e.g. self-merge, wrong confirmation, SHA mismatch). |
|
||||
| `gitea_review_pr` | `pr_number: int`, `event: str`, `body: str`, `merge: bool`, `merge_method: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict representing legacy review output. | Backward compatibility wrapper; delegates to review/merge logic. |
|
||||
| `gitea_delete_branch` | `branch: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict indicating branch deletion status. | Fails on protected branches or non-existent refs. |
|
||||
|
||||
### 2.3 File, Identity, and Utility Tools
|
||||
|
||||
| Tool Name | Parameters | Return Payload Shape | Error Behavior / Edge Cases |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `gitea_get_file` | `filepath: str`, `ref: str`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict containing metadata and Base64 content of the target file. | Fails if path or reference branch does not exist. |
|
||||
| `gitea_commit_files` | `files: list[dict]`, `message: str`, `branch: str \| None`, `new_branch: str \| None`, `remote: str`, `host: str \| None`, `org: str \| None`, `repo: str \| None` | Dict describing commit hash and ref state. | Fails on file path conflicts or commit collisions. |
|
||||
| `gitea_whoami` | `remote: str`, `host: str \| None` | Dict detailing verified login user (e.g., `sysadmin`). | Alias targets: `gitea_get_authenticated_user`, `gitea_get_current_user` must be preserved. |
|
||||
| `gitea_get_profile` | `remote: str`, `host: str \| None`, `resolve_identity: bool` | Dict of loaded profile constraints and active configuration details. | Fails closed on invalid/missing profile specs. |
|
||||
| `gitea_mirror_refs` | `apply: bool`, `force: bool` | Dict summarizing mirrored branch/tag logs. | Fails on Git CLI mirror action exceptions. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Staged Refactoring Plan
|
||||
|
||||
We will perform the refactoring in five discrete stages. Each stage will land as its own independent PR to master, verifying that the codebase compiles and passes the complete test suite at each step.
|
||||
|
||||
### Stage 1: API and Client Core Extraction
|
||||
* **Goal:** Extract common network request wrappers, pagination handlers, and HTTP exception conversions.
|
||||
* **Target File:** `gitea_tools/client.py`
|
||||
* **Contents:** `api_request`, `api_get_all`, HTTP error maps, and token/credential redaction helper `_redact`.
|
||||
|
||||
### Stage 2: Auth and Configuration Extraction
|
||||
* **Goal:** Extract Gitea profile parsers, credential loading logic, and helper scripts.
|
||||
* **Target File:** `gitea_tools/config.py`
|
||||
* **Contents:** `get_auth_header`, `get_profile`, `repo_api_url`, and profile config schemas.
|
||||
|
||||
### Stage 3: Audit Logging and Security Gates
|
||||
* **Goal:** Extract security filters, audit logging mechanisms, and metadata decorators.
|
||||
* **Target File:** `gitea_tools/audit.py`
|
||||
* **Contents:** `AuditSink`, `_audited`, and audit message templates.
|
||||
|
||||
### Stage 4: Tool Implementations (Domain-Driven Modules)
|
||||
* **Goal:** Group and move the core implementation logic of the 24 tools out of `mcp_server.py`.
|
||||
* **Target Files:**
|
||||
* `gitea_tools/issues.py` — Issues, labels, and mark status tools.
|
||||
* `gitea_tools/prs.py` — PRs, reviews, merge gating, and branch delete.
|
||||
* `gitea_tools/files.py` — File retrieval and atomic commits.
|
||||
* `gitea_tools/identity.py` — whoami and runtime profile descriptions.
|
||||
* `gitea_tools/utilities.py` — Mirroring scripts and miscellaneous tasks.
|
||||
|
||||
### Stage 5: Final Tool Registration Layer
|
||||
* **Goal:** Clean up the root `mcp_server.py` to be a pure registration layer.
|
||||
* **Contents:** Imports the modular functions from the `gitea_tools` package and wraps them inside the standard FastMCP `@mcp.tool()` decorators.
|
||||
@@ -1,68 +0,0 @@
|
||||
# Multi-Service MCP Profile and Configuration Model
|
||||
|
||||
- **Status:** Design (no implementation in this repo yet)
|
||||
- **Issue:** #76 (parent umbrella: #75; boundary decision: ADR-0001, #71)
|
||||
- **Date:** 2026-07-02
|
||||
|
||||
## 1. Purpose and Scope
|
||||
|
||||
Extend the existing Gitea execution-profile model (`docs/gitea-execution-profiles.md`) into a generic **per-service** MCP profile/config model. This supports integrating Jenkins and GlitchTip into the MCP Control Plane while strictly preserving isolation and fail-closed safety.
|
||||
|
||||
**Crucial Constraints:**
|
||||
* The shared profile/config model is a **schema / library**, **not a shared credential pool**.
|
||||
* Tokens remain **service-local**; profiles are **per service**.
|
||||
* Orchestrators **must not** directly hold every service credential.
|
||||
|
||||
## 2. Profile Schema (Per Service)
|
||||
|
||||
The schema reuses the proven Gitea field model, adapted per service.
|
||||
|
||||
```json
|
||||
{
|
||||
"profile_name": "readonly-metrics",
|
||||
"service": "glitchtip",
|
||||
"token_source_name": "GLITCHTIP_API_TOKEN_READONLY",
|
||||
"allowed_operations": [
|
||||
"glitchtip.event.read",
|
||||
"glitchtip.issue.read"
|
||||
],
|
||||
"forbidden_operations": [
|
||||
"glitchtip.issue.resolve",
|
||||
"glitchtip.issue.delete"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Schema Rules
|
||||
|
||||
* `allowed_operations` are **namespaced** (e.g., `gitea.issue.create`, `jenkins.build.read`, `glitchtip.event.read`).
|
||||
* `forbidden_operations`, if present, **always override** `allowed_operations`.
|
||||
* `token_source_name` records the source **name only, never the value**. Tokens must never be printed, logged, or included in telemetry.
|
||||
|
||||
## 3. Fail-Closed Behavior
|
||||
|
||||
The model enforces strict fail-closed constraints before any network call occurs:
|
||||
* **Missing Profile:** If a requested profile is undefined for the target service, the operation fails immediately.
|
||||
* **Missing Credentials:** If the `token_source_name` cannot be resolved to a valid token at runtime, the operation fails immediately without retrying or prompting.
|
||||
|
||||
## 4. Environment Overrides
|
||||
|
||||
Profiles can be dynamically overridden or injected via environment variables, following the established hierarchy:
|
||||
|
||||
1. **Explicit Environment Variable:** (Highest precedence) e.g., `MCP_GLITCHTIP_TOKEN` overrides any JSON profile.
|
||||
2. **Profile Mapping in JSON:** Resolved via `token_source_name` (e.g., `GLITCHTIP_API_TOKEN_READONLY`) mapping to an environment variable or secret store.
|
||||
3. **No Auth:** Fails closed.
|
||||
|
||||
## 5. Audit Logging
|
||||
|
||||
To maintain accountability across multi-service workflows, all mutating actions must include the audit identity and source:
|
||||
* The audit log must record the `profile_name`, the orchestrator source (e.g., `sysadmin`, `jenkins-mcp`), and the action taken.
|
||||
* The audit system must sanitize all output to ensure tokens are stripped (see `safety-model.md`).
|
||||
|
||||
## 6. Backward Compatibility
|
||||
|
||||
The existing Gitea profile behavior (`gitea_whoami`, etc.) remains strictly backward compatible. The generic profile library will parse existing Gitea profile objects without requiring them to migrate their schemas, defaulting the `service` attribute to `gitea`.
|
||||
|
||||
## 7. Implementation Boundary
|
||||
|
||||
Per the namespace decisions in #71 and #75, this generic model belongs in the `common` package or library. It will be imported by `gitea-mcp` (this repo), `jenkins-mcp`, and `glitchtip-mcp` without forcing a monolithic architecture.
|
||||
@@ -208,18 +208,17 @@ git diff --cached | grep -nEi "authorization: (basic|bearer)|password|token=[A-Z
|
||||
|
||||
---
|
||||
|
||||
## 8. Unit tests vs. Docker integration tests
|
||||
## 8. Unit tests vs. future Docker integration tests
|
||||
|
||||
* **Unit tests (default):** fast, fully mocked, no network, no keychain.
|
||||
* **Unit tests (today, default):** fast, fully mocked, no network, no keychain.
|
||||
This is where the vast majority of coverage lives and where new tests should
|
||||
go. They must stay fast and must not require credentials.
|
||||
* **Docker/local-Gitea integration tests (#66, `tests/integration/`):** opt-in
|
||||
and skipped by default — enabled only by `GITEA_INTEGRATION=1` and run
|
||||
against a pinned, disposable Gitea container
|
||||
(`tests/integration/gitea-integration up|token|down`). They validate real
|
||||
API behavior (pagination, permissions, label endpoints, error payloads) that
|
||||
mocks cannot prove. They must not use production credentials and must not
|
||||
leak tokens. See [`../tests/integration/README.md`](../tests/integration/README.md).
|
||||
* **Docker/local-Gitea integration tests (planned, see #66):** opt-in and
|
||||
skipped by default, gated behind an explicit environment variable and run
|
||||
against a pinned, disposable Gitea container. They validate real API behavior
|
||||
(pagination, permissions, label/PR-review endpoints, error payloads) that
|
||||
mocks cannot prove. They must not require production credentials and must not
|
||||
leak tokens.
|
||||
|
||||
Rule of thumb: prove **logic and request-shaping** with unit tests; reserve
|
||||
integration tests for **real-server compatibility**. Do not convert unit tests
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
# Label Taxonomy
|
||||
|
||||
This document catalogs the issue labels used for MCP workflows, including Jenkins and GlitchTip (observability).
|
||||
|
||||
> **Approval Required:** Do not create or apply new labels in `manage_labels.py` without explicit owner approval of this document.
|
||||
|
||||
## Existing Labels
|
||||
|
||||
* **`jenkins`**
|
||||
* Description: Jenkins integration
|
||||
* Color: `d93f0b`
|
||||
* Use: Used to mark issues, PRs, or tasks that involve the `jenkins-mcp` boundaries, CI/CD designs, or build failures.
|
||||
|
||||
* **`glitchtip`**
|
||||
* Description: GlitchTip integration
|
||||
* Color: `b60205`
|
||||
* Use: Used to mark issues related to the `glitchtip-mcp` boundary and observability integration.
|
||||
|
||||
## Proposed / Missing Labels
|
||||
|
||||
* **`observability`**
|
||||
* Proposed Description: Observability, metrics, and monitoring tasks
|
||||
* Proposed Color: `5319e7`
|
||||
* Use: Broader than GlitchTip alone; covers logging, metrics, traces, and general observability pipeline improvements.
|
||||
|
||||
* **`source:glitchtip`**
|
||||
* Proposed Description: Issue filed automatically by GlitchTip orchestration
|
||||
* Proposed Color: `b60205`
|
||||
* Use: Applied automatically by the orchestrator when a GlitchTip error event is converted into a Gitea issue.
|
||||
|
||||
* **`status:triage`**
|
||||
* Proposed Description: Issue needs human or orchestrator triage
|
||||
* Proposed Color: `fbca04`
|
||||
* Use: Used for incoming issues (especially automated ones like `source:glitchtip`) that have not yet been evaluated for priority or resolution.
|
||||
@@ -1,138 +0,0 @@
|
||||
# LLM-Agent-SHA — Opaque Agent Attribution (Phase 0)
|
||||
|
||||
Convention for attributing work to a specific LLM session/workstream across
|
||||
issues, branches, PRs, and review handoffs, without exposing a human or model
|
||||
identity. Approved by the owner decision on issue #86
|
||||
(`#issuecomment-1354`); this document implements **Phase 0 only**.
|
||||
|
||||
## The one rule that matters
|
||||
|
||||
`LLM-Agent-SHA` is **informational attribution metadata only**. It must never
|
||||
be used for authentication, authorization, review eligibility, merge
|
||||
eligibility, profile permissions, or any other security decision.
|
||||
|
||||
The security gates remain, unchanged:
|
||||
|
||||
- the **authenticated Gitea user** (self-review/self-merge protection),
|
||||
- the **active MCP profile** and its `allowed_operations`
|
||||
(see [`gitea-execution-profiles.md`](gitea-execution-profiles.md)),
|
||||
- the fail-closed eligibility checks in `gitea_check_pr_eligibility`.
|
||||
|
||||
Two sessions with different `LLM-Agent-SHA` values that authenticate as the
|
||||
same Gitea user are **the same actor** for review/merge safety. A different
|
||||
SHA never unlocks self-review or self-merge. `tests/test_llm_agent_sha.py`
|
||||
proves the eligibility logic never consults the SHA.
|
||||
|
||||
## Format
|
||||
|
||||
```text
|
||||
LLM-Agent-SHA: llm-<12 lowercase hex chars>
|
||||
```
|
||||
|
||||
Validation regex:
|
||||
|
||||
```text
|
||||
^llm-[0-9a-f]{12}$
|
||||
```
|
||||
|
||||
Examples: `llm-8f3a9c2d6b41`, `llm-41d0e7aa9f2c`, `llm-b7c93d441a08`.
|
||||
|
||||
### Generation
|
||||
|
||||
Generate 48 random bits, e.g. `python3 -c "import secrets; print('llm-' +
|
||||
secrets.token_hex(6))"`, or hash a non-secret session UUID. An
|
||||
operator-provided opaque ID is also fine.
|
||||
|
||||
Do **not** derive the value from any of:
|
||||
|
||||
- a Gitea token or other secret,
|
||||
- an email address or username,
|
||||
- a machine hostname or private filesystem path,
|
||||
- a model or provider name,
|
||||
- conversation contents.
|
||||
|
||||
The SHA must contain no model name, provider name, human name, email,
|
||||
hostname, token, private path, or conversation-derived content. It is safe to
|
||||
include in PR bodies, issue comments, and audit logs — and only there.
|
||||
|
||||
## Lifetime
|
||||
|
||||
Canonical lifetime is **per PR/workstream**: pick one SHA when starting an
|
||||
issue and keep it through the branch, PR, and handoff for that workstream. A
|
||||
per-session SHA is acceptable when the session maps cleanly to one
|
||||
workstream. Do not reuse a SHA across unrelated workstreams.
|
||||
|
||||
## Placement
|
||||
|
||||
Phase 0 uses **visible markdown metadata blocks** (not hidden HTML
|
||||
comments). Include the block in PR bodies and review handoffs; keep it out of
|
||||
ordinary comments unless attribution is genuinely useful there.
|
||||
|
||||
**Never put the SHA in branch or worktree names.** Branches stay
|
||||
issue-linked and human-readable (`docs/issue-86-llm-agent-sha-phase0`), per
|
||||
the branch standard.
|
||||
|
||||
### Handoff metadata block (implementer → PR body / handoff report)
|
||||
|
||||
```markdown
|
||||
LLM Handoff Metadata:
|
||||
- LLM-Agent-SHA: llm-8f3a9c2d6b41
|
||||
- LLM-Role: implementer
|
||||
- Authenticated-Gitea-User: jcwalker3
|
||||
- MCP-Profile: gitea-default
|
||||
- Branch: docs/example-branch
|
||||
- Worktree: branches/docs-example-branch
|
||||
- Self-review allowed: no
|
||||
```
|
||||
|
||||
### Review metadata block (reviewer → review comment)
|
||||
|
||||
```markdown
|
||||
Review Metadata:
|
||||
- LLM-Agent-SHA: llm-41d0e7aa9f2c
|
||||
- LLM-Role: reviewer
|
||||
- Authenticated-Gitea-User: sysadmin
|
||||
- MCP-Profile: prgs-reviewer
|
||||
- Eligibility: passed
|
||||
```
|
||||
|
||||
## Same SHA vs same user vs same profile
|
||||
|
||||
Reviewers and operators must keep three distinct identities straight:
|
||||
|
||||
| Comparison | Meaning | Effect on eligibility |
|
||||
|---|---|---|
|
||||
| same `LLM-Agent-SHA` | same LLM session/workstream wrote both artifacts | **none — attribution only** |
|
||||
| same authenticated Gitea user | same Gitea actor | **blocks** self-review / self-merge, regardless of SHA |
|
||||
| same MCP profile | same capability set | governs `allowed_operations` (what actions are permitted at all) |
|
||||
|
||||
Concretely: an implementer session (`llm-8f3a…`, user `jcwalker3`) and a
|
||||
would-be reviewer session (`llm-41d0…`, also user `jcwalker3`) have different
|
||||
SHAs but the **same Gitea user** — the reviewer session is still the PR
|
||||
author to Gitea and must not review, approve, or merge. Review handoffs
|
||||
require a genuinely different authenticated user (e.g. `sysadmin` /
|
||||
`prgs-reviewer`).
|
||||
|
||||
## Phase 0 scope (and what is deferred)
|
||||
|
||||
Phase 0 is documentation, handoff/review templates, and negative tests only.
|
||||
Deferred to later owner-approved phases; none of this exists yet:
|
||||
|
||||
- launcher-enforced SHA generation,
|
||||
- `LLM_AGENT_SHA` / `LLM_AGENT_ROLE` environment injection,
|
||||
- `gitea_whoami` returning SHA/role,
|
||||
- automatic PR body injection by MCP tools,
|
||||
- audit schema changes requiring the SHA,
|
||||
- release/orchestrator lineage tracking.
|
||||
|
||||
MCP tools neither read nor emit the SHA. Setting an `LLM_AGENT_SHA`
|
||||
environment variable has no effect on any tool; the negative tests assert
|
||||
eligibility results are byte-identical with and without it.
|
||||
|
||||
## Related documents
|
||||
|
||||
- [`llm-workflow-runbooks.md`](llm-workflow-runbooks.md) — the runbooks whose
|
||||
handoffs carry these blocks
|
||||
- [`gitea-execution-profiles.md`](gitea-execution-profiles.md) — profiles and
|
||||
`allowed_operations` (the real permission gate)
|
||||
- [`safety-model.md`](safety-model.md) — audit, redaction, confirmation gates
|
||||
@@ -45,18 +45,6 @@ Use any eligible reviewer profile to review PR #N.
|
||||
Use any eligible merger profile to merge PR #N if checks pass.
|
||||
```
|
||||
|
||||
### Attribution: `LLM-Agent-SHA` (metadata only)
|
||||
|
||||
Sessions may attribute their work with an opaque `LLM-Agent-SHA`
|
||||
(`llm-<12 lowercase hex>`, e.g. `llm-8f3a9c2d6b41`) in PR-body and
|
||||
review-handoff metadata blocks — see
|
||||
[`llm-agent-sha.md`](llm-agent-sha.md) for the full convention. It is
|
||||
**attribution only**: eligibility is decided solely by the authenticated
|
||||
Gitea user and the profile's allowed operations. Two sessions with different
|
||||
SHAs under the same Gitea user are the same actor — a different SHA never
|
||||
permits self-review or self-merge. Keep the SHA out of branch and worktree
|
||||
names.
|
||||
|
||||
## Prerequisites: canonical config + thin launchers
|
||||
|
||||
Runtime profiles live in **one canonical JSON file**, referenced by every LLM
|
||||
@@ -124,35 +112,8 @@ and the two `GITEA_MCP_*` variables — never a token or password:
|
||||
}
|
||||
```
|
||||
|
||||
### Dual-profile MCP launcher pattern (Recommended)
|
||||
|
||||
To avoid the bottleneck of relaunching/restarting the MCP server to switch between author and reviewer roles, the client should register **both** profiles concurrently as separate server instances in the client's MCP configuration:
|
||||
|
||||
```json
|
||||
"gitea-author": {
|
||||
"command": "/path/to/Gitea-Tools/venv/bin/python3",
|
||||
"args": ["/path/to/Gitea-Tools/mcp_server.py"],
|
||||
"env": {
|
||||
"GITEA_MCP_CONFIG": "/path/to/.config/gitea-tools/profiles.json",
|
||||
"GITEA_MCP_PROFILE": "prgs-author"
|
||||
}
|
||||
},
|
||||
"gitea-reviewer": {
|
||||
"command": "/path/to/Gitea-Tools/venv/bin/python3",
|
||||
"args": ["/path/to/Gitea-Tools/mcp_server.py"],
|
||||
"env": {
|
||||
"GITEA_MCP_CONFIG": "/path/to/.config/gitea-tools/profiles.json",
|
||||
"GITEA_MCP_PROFILE": "prgs-reviewer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **Tool Namespaces:** Tool calls become distinct and identity-scoped in the client UI:
|
||||
* `mcp__gitea-author__*` (for creating issues, pushing branches, creating PRs)
|
||||
* `mcp__gitea-reviewer__*` (for reviewing PRs, approving, requesting changes, merging)
|
||||
* **Trust Model:** Separate tokens remain separate in the keychain/environment. Each instance operates under its own `GITEA_MCP_PROFILE` and enforces its own `allowed_operations`. A runtime `whoami` identity check is still performed independently, and self-review/self-merge checks remain strictly mandatory. The dual-server pattern is a operational convenience and never a security bypass.
|
||||
* **Reviewer-Identity PR Creation Deadlock:** Reviewer/merge identities must not create PRs or push branches. Doing so makes the reviewer identity the PR author in Gitea, blocking subsequent independent review and causing a review deadlock. Normally, PRs must be created by the author/work identity (`gitea-author`), leaving the reviewer identity (`gitea-reviewer`) clean and available for independent review and merge.
|
||||
* **Fallback:** If the dual-profile MCP launcher pattern is not supported or configured in the client, the LLM must relaunch or restart the client/MCP with the correct profile environment variable before claiming or working on any tasks.
|
||||
Run the same server as several launcher entries (e.g. `-author`, `-reviewer`,
|
||||
`-merger`), each pointing at a different `GITEA_MCP_PROFILE`.
|
||||
|
||||
## Setup runbook — interactive menu
|
||||
|
||||
@@ -227,7 +188,7 @@ tied to an issue number so the work is traceable end to end:
|
||||
| Issue | `#123` (claimed with `status:in-progress`) |
|
||||
| Branch | `(fix\|feat\|docs\|chore)/issue-123-<slug>` (review: `review/pr-456-<slug>`) |
|
||||
| Worktree | `branches/fix-issue-123-<slug>` (slashes → hyphens) |
|
||||
| PR | body says `Closes #123` or `Fixes #123` (closes issue); `Implements #123` or `Refs #123` (does NOT close) |
|
||||
| PR | body says `Closes #123` (closes) or `Refs #123` (related) |
|
||||
| Cleanup | remove remote+local branch + worktree folder; drop `status:in-progress` |
|
||||
|
||||
`scripts/worktree-start` **rejects** implementation branches that are not
|
||||
@@ -313,8 +274,7 @@ touching anything.
|
||||
`fix/...` / `docs/...`); `cd` into that worktree; implement narrowly; add or
|
||||
update tests if behavior changes; run the full suite; commit with an
|
||||
issue-linked message; open a PR to `master`. **Do not** review or merge your
|
||||
own PR. Include an `LLM Handoff Metadata` block (with `LLM-Agent-SHA`) in
|
||||
the PR body — see [`llm-agent-sha.md`](llm-agent-sha.md).
|
||||
own PR.
|
||||
- **Prompt:** `Use an author profile to implement issue #N and open a PR to
|
||||
master. Do not self-review or self-merge.`
|
||||
|
||||
@@ -325,11 +285,7 @@ touching anything.
|
||||
- **Steps:** confirm identity + eligibility (menu eligibility check or
|
||||
`gitea_check_pr_eligibility`); read the diff; confirm scope matches the linked
|
||||
issue; post the review (`comment` / `request_changes` / `approve`) via the
|
||||
gated review tool. Pin the reviewed head SHA where supported. Include a
|
||||
`Review Metadata` block (with your own `LLM-Agent-SHA`) in the review —
|
||||
and remember: a different `LLM-Agent-SHA` does **not** make you a different
|
||||
actor; only a different authenticated Gitea user does
|
||||
([`llm-agent-sha.md`](llm-agent-sha.md)).
|
||||
gated review tool. Pin the reviewed head SHA where supported.
|
||||
- **Prompt:** `Use any eligible reviewer profile to review PR #N. Approve only
|
||||
if scope matches issue #M and checks pass; otherwise request changes.`
|
||||
|
||||
@@ -364,29 +320,6 @@ touching anything.
|
||||
files, detected secret, or any production/deploy behavior — **stop, report the
|
||||
blocker, and take no mutating action.** Fail closed; never work around a gate.
|
||||
|
||||
## Controller Handoff Summary (required, every task)
|
||||
|
||||
Every task — implementation, review, merge, triage, documentation,
|
||||
discussion-only, or blocked planning — **must end with a
|
||||
`Controller Handoff Summary`** so a controller LLM can pick up the state
|
||||
without rereading the conversation. The canonical format and rules live in the
|
||||
portable skill:
|
||||
[`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) §K.
|
||||
|
||||
Sections (in order): Work performed · Current state (repo, branch/master
|
||||
commit, issue #s, PR #s, complete/blocked/ready-for-review/discussion-only) ·
|
||||
Files changed · Validation · Issues encountered · Review needed? (one of the
|
||||
five fixed answers) · Next recommended action · Safety confirmations
|
||||
(no self-review; no self-merge; no release/tag changes unless requested; no
|
||||
secrets; no production access unless authorized).
|
||||
|
||||
Hard rules: never omit it; never bury blockers earlier only; an opened PR
|
||||
means "Review needed — PR is open"; a blocked merge names the exact gate;
|
||||
discussion-only comments need owner/design feedback, not code review; any
|
||||
touched release state names the exact tag/commit and why. Design debates
|
||||
belong in **discussion/RFC issues** (e.g. #100 `profiles.json v2`) — comment
|
||||
on the issue, create no branches/PRs, and end the comment with this summary.
|
||||
|
||||
## Fail-closed behavior
|
||||
|
||||
Before any mutating action the workflow verifies identity, active profile,
|
||||
@@ -458,7 +391,6 @@ scripts/release-tag v0.4.0 --notes-file /tmp/release-notes.md --push
|
||||
|
||||
- [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable cross-project LLM workflow skill.
|
||||
- [`gitea-execution-profiles.md`](gitea-execution-profiles.md) — the profile model.
|
||||
- [`llm-agent-sha.md`](llm-agent-sha.md) — opaque agent attribution metadata (never an eligibility input).
|
||||
- [`safety-model.md`](safety-model.md) — trust boundaries and audit logging.
|
||||
- [`tool-boundaries.md`](tool-boundaries.md) — per-tool allowed operations.
|
||||
- [`credential-isolation.md`](credential-isolation.md) — credential handling.
|
||||
|
||||
+4
-18
@@ -53,7 +53,7 @@ mcp = FastMCP("gitea-tools", instructions=(
|
||||
def extract_linked_issue_numbers(text: str | None, branch_name: str | None = None) -> list[int]:
|
||||
issues = set()
|
||||
if text:
|
||||
pattern = re.compile(r'(?i)(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement[s]?|implemented)\s+#(\d+)')
|
||||
pattern = re.compile(r'(?i)(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|ref[s]?)\s+#(\d+)')
|
||||
issues.update(int(m) for m in pattern.findall(text))
|
||||
if branch_name:
|
||||
pattern = re.compile(r'(?i)issue-(\d+)')
|
||||
@@ -1098,30 +1098,16 @@ def gitea_merge_pr(
|
||||
payload["MergeMessageField"] = message
|
||||
api_request("POST", merge_url, auth, payload)
|
||||
# Best-effort read-back of the merge commit SHA (redacted on error).
|
||||
merged = None
|
||||
try:
|
||||
merged = api_request(
|
||||
"GET", f"{repo_api_url(h, o, r)}/pulls/{pr_number}", auth
|
||||
)
|
||||
result["merge_commit"] = (merged or {}).get("merged_commit_sha")
|
||||
|
||||
cleanup = cleanup_in_progress_for_pr(merged or {}, remote, host, org, repo)
|
||||
result["cleanup_status"] = cleanup.get("cleanup_status")
|
||||
except Exception:
|
||||
result["merge_commit"] = None
|
||||
|
||||
# Tracker cleanup (#98): never blocks the merge, and always surfaces an
|
||||
# explicit cleanup_status once the merge mutation has happened. Cleanup
|
||||
# needs the PR title/body/branch, which only the read-back payload
|
||||
# carries here — so a failed read-back is an explicit skip, not a
|
||||
# silent one.
|
||||
if merged is None:
|
||||
result["cleanup_status"] = "skipped (merge read-back failed)"
|
||||
else:
|
||||
try:
|
||||
cleanup = cleanup_in_progress_for_pr(merged, remote, host, org, repo)
|
||||
result["cleanup_status"] = cleanup.get("cleanup_status")
|
||||
except Exception as cleanup_exc: # noqa: BLE001 — redact before surfacing
|
||||
result["cleanup_status"] = (
|
||||
f"skipped (cleanup error: {_redact(str(cleanup_exc))})"
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 — redact before surfacing
|
||||
reasons.append(f"merge failed: {_redact(str(exc))}")
|
||||
return result
|
||||
|
||||
@@ -41,18 +41,6 @@ editing, deleting, or `chmod`-ing files; docs; scripts; commits; pushes; and PRs
|
||||
Reading the repo, running read-only status/`git log`, and creating/claiming the
|
||||
issue itself are allowed from the orchestration checkout without a prior issue.
|
||||
|
||||
Additional issue-first rules:
|
||||
|
||||
- Do not implement code without an issue unless explicitly authorized.
|
||||
- **Design-only work uses a discussion/RFC issue** — create one or comment on
|
||||
the existing one. Design debates belong on the issue, where other LLMs
|
||||
comment directly. Discussion-only tasks must **not** create branches or PRs;
|
||||
their comments should include recommendations, risks, open questions, and a
|
||||
Controller Handoff Summary (§K).
|
||||
- **If the repo/tracker home for the work is unclear, stop and ask for an
|
||||
owner decision.** Do not create a new repository or a new tracker unless
|
||||
explicitly approved by the owner.
|
||||
|
||||
## B. Isolated worktree rule
|
||||
|
||||
**Never implement or review in the main checkout.** The main checkout is for
|
||||
@@ -90,8 +78,8 @@ is maintained by:
|
||||
- the branch name (contains the issue number),
|
||||
- a claim comment on the issue, e.g.
|
||||
`Claimed. Branch: fix/issue-123-short-description. Worktree: branches/fix-issue-123-short-description.`,
|
||||
- the PR body — `Closes #123` or `Fixes #123` when the PR should close the issue
|
||||
(do NOT use `Implements #123` or `Refs #123` to close, as Gitea will not auto-close),
|
||||
- the PR body — `Closes #123` when the PR should close the issue, `Refs #123`
|
||||
when related but not closing,
|
||||
- cleanup after merge — remove the remote branch, local branch, and the issue
|
||||
worktree folder, and drop `status:in-progress`.
|
||||
|
||||
@@ -116,17 +104,16 @@ interpreter path, or create a venv inside the branch folder.
|
||||
|
||||
## C. Identity and profile safety
|
||||
|
||||
- Use canonical execution profiles where available; the profile is the role, not the LLM. A task selects a profile; a profile is not permanently assigned.
|
||||
- Use canonical execution profiles where available; the profile is the role, not
|
||||
the LLM. A task selects a profile; a profile is not permanently assigned.
|
||||
- **Author and reviewer identities must be distinct.**
|
||||
- Never place raw tokens/passwords in an LLM/MCP client config. Reference secrets by keychain id or environment variable name only. Prefer a single canonical config file selected by two env vars, e.g.:
|
||||
- Never place raw tokens/passwords in an LLM/MCP client config. Reference secrets
|
||||
by keychain id or environment variable name only. Prefer a single canonical
|
||||
config file selected by two env vars, e.g.:
|
||||
- `GITEA_MCP_CONFIG` — path to the canonical profiles file
|
||||
- `GITEA_MCP_PROFILE` — the profile to activate
|
||||
- **Dual-Profile MCP Launcher Pattern (Recommended):** To avoid relaunch bottlenecks and PR-author deadlocks, register multiple instances of the same MCP server in the client's configuration simultaneously (e.g., `gitea-author` and `gitea-reviewer`), each pointing to its respective `GITEA_MCP_PROFILE`.
|
||||
- Tool calls become namespace-scoped: `mcp__gitea-author__*` and `mcp__gitea-reviewer__*`.
|
||||
- **Trust Model:** Separate tokens remain separate. Profile gates enforce allowed operations, `whoami` is still checked, and self-review/self-merge prevention remains mandatory. This pattern is for convenience and does not bypass security gates.
|
||||
- **Deadlock Warning:** Reviewer/merge identities must not be used to create PRs, as this makes the reviewer the PR author in Gitea and blocks independent review. PRs should normally be created by the author/work identity, keeping the reviewer identity available for reviews.
|
||||
- **Fallback:** If a dual-server launcher is not available in the client, relaunch or restart the client with the correct profile environment variable before claiming work.
|
||||
- **If the authenticated user equals the PR author, stop** — no self-review, no self-merge.
|
||||
- **If the authenticated user equals the PR author, stop** — no self-review, no
|
||||
self-merge.
|
||||
|
||||
## D. Branch naming
|
||||
|
||||
@@ -175,12 +162,7 @@ Worktree folder = branch with `/` replaced by `-`
|
||||
|
||||
## G. Merge / cleanup workflow
|
||||
|
||||
Only an eligible (non-author) reviewer merges. Before merging: always verify
|
||||
the authenticated identity **and** the PR author; respect runtime profile
|
||||
gates; run independent validation (do not trust the author's reported
|
||||
results); and merge with a **pinned head SHA** and, where supported, the
|
||||
**expected changed-file set**, so a moved head or widened diff refuses the
|
||||
merge. After a real merge:
|
||||
Only an eligible (non-author) reviewer merges. After a real merge:
|
||||
|
||||
1. Confirm remote `master` actually contains the merge commit (A PR is not done just because `master` moved. A PR is done only when: Gitea reports the PR merged or reconciliation documents equivalent content on `master`; remote `master` contains the expected content; linked issues are closed; `status:in-progress` is removed).
|
||||
2. Close/release the issue.
|
||||
@@ -248,132 +230,6 @@ Ready-to-copy templates live in [`templates/`](templates/):
|
||||
- [`worktree-cleanup.md`](templates/worktree-cleanup.md) — clean up after merge.
|
||||
- [`release-tag.md`](templates/release-tag.md) — create a release tag.
|
||||
|
||||
## K. Controller Handoff Summary (required, every task)
|
||||
|
||||
Every LLM task **must end with a `Controller Handoff Summary`** — whether the
|
||||
task was implementation, review, merge, issue triage, documentation,
|
||||
discussion-only, or blocked planning. It lets a controller LLM understand the
|
||||
current state immediately, without rereading the conversation.
|
||||
|
||||
Rules:
|
||||
|
||||
- Never omit the summary.
|
||||
- Never bury blockers in earlier text only — they must appear here.
|
||||
- If you opened a PR, state clearly that review is needed.
|
||||
- If you reviewed but could not merge, name the exact gate that blocked it.
|
||||
- If you only commented on a discussion issue, say no code review is needed
|
||||
but owner/design feedback may be needed.
|
||||
- If release state was touched, state exactly which tag/commit changed and why.
|
||||
- If blocked (permissions, missing repo, missing second reviewer identity,
|
||||
stale dependency, unclear tracker home): stop and report clearly; **never
|
||||
bypass classifiers, profile gates, missing permissions, or live-consent
|
||||
requirements**; give the owner concrete options.
|
||||
|
||||
Required format:
|
||||
|
||||
```md
|
||||
## Controller Handoff Summary
|
||||
|
||||
### Work performed
|
||||
|
||||
Briefly state what was done.
|
||||
|
||||
### Current state
|
||||
|
||||
Include:
|
||||
- current repo
|
||||
- current branch or master commit
|
||||
- issue number(s)
|
||||
- PR number(s), if any
|
||||
- whether work is complete, blocked, ready for review, or discussion-only
|
||||
|
||||
### Files changed
|
||||
|
||||
List files changed, or say `None`.
|
||||
|
||||
### Validation
|
||||
|
||||
List commands run and results, or say `Not applicable — discussion only`.
|
||||
|
||||
### Issues encountered
|
||||
|
||||
List errors, confusing state, permission/profile problems, stale branches,
|
||||
failing tests, missing labels, or blocked decisions.
|
||||
|
||||
### Review needed?
|
||||
|
||||
Say one of:
|
||||
- `No review needed — discussion/comment only`
|
||||
- `Review needed — PR is open`
|
||||
- `Independent non-author review needed`
|
||||
- `Owner decision needed`
|
||||
- `Blocked`
|
||||
|
||||
### Next recommended action
|
||||
|
||||
State exactly what should happen next.
|
||||
|
||||
### Safety confirmations
|
||||
|
||||
Confirm:
|
||||
- no self-review
|
||||
- no self-merge
|
||||
- no release/tag changes unless explicitly requested
|
||||
- no secrets committed
|
||||
- no production access used unless explicitly authorized
|
||||
```
|
||||
|
||||
### Example blocked handoff
|
||||
|
||||
```md
|
||||
## Example blocked handoff
|
||||
|
||||
### Work performed
|
||||
|
||||
Audited phase-2 MCP Control Plane planning. Found target repo
|
||||
`mcp-control-plane` does not exist. Prepared issue pack but did not file it.
|
||||
|
||||
### Current state
|
||||
|
||||
- Repo: `Scaled-Tech-Consulting/Gitea-Tools`, unmodified
|
||||
- Target repo: `mcp-control-plane`, missing
|
||||
- Issues: none open in Gitea-Tools
|
||||
- PRs: none open
|
||||
- Status: blocked pending owner decision
|
||||
|
||||
### Files changed
|
||||
|
||||
None.
|
||||
|
||||
### Validation
|
||||
|
||||
Tracker/repo audit only. No code validation required.
|
||||
|
||||
### Issues encountered
|
||||
|
||||
Repo creation was denied by permission/classifier because it would be scope
|
||||
escalation without live consent.
|
||||
|
||||
### Review needed?
|
||||
|
||||
Owner decision needed.
|
||||
|
||||
### Next recommended action
|
||||
|
||||
Owner must choose:
|
||||
1. create `Scaled-Tech-Consulting/mcp-control-plane`
|
||||
2. authorize repo creation while present
|
||||
3. file phase-2 issues in Gitea-Tools instead
|
||||
|
||||
### Safety confirmations
|
||||
|
||||
- no self-review
|
||||
- no self-merge
|
||||
- no release/tag changes
|
||||
- no secrets committed
|
||||
- no production access used
|
||||
```
|
||||
|
||||
## Adapting to a project
|
||||
|
||||
Replace these project-specific names when copying the skill elsewhere:
|
||||
@@ -386,7 +242,7 @@ Replace these project-specific names when copying the skill elsewhere:
|
||||
| `branches/` | Ignored worktree directory | `branches/` |
|
||||
| helper scripts | Worktree helpers | `scripts/worktree-start` / `-review` / `-clean` |
|
||||
|
||||
The rules in §A–§K are project-agnostic and should not change.
|
||||
The rules in §A–§I are project-agnostic and should not change.
|
||||
|
||||
## Versioning And Tagging
|
||||
|
||||
@@ -407,14 +263,6 @@ Tags must:
|
||||
**Never tag** feature branches, dirty worktrees, unreviewed or self-authored
|
||||
work, or commits not present on remote `master`.
|
||||
|
||||
Additional tag rules:
|
||||
|
||||
- Do **not** create, move, delete, or push tags unless explicitly instructed.
|
||||
- Tag only **after** the intended PR is merged, and tag only the **verified
|
||||
final master merge commit** (never the PR branch head unless the merge
|
||||
commit is exactly that commit).
|
||||
- Always **report the tag target commit** in the final report / handoff.
|
||||
|
||||
Release process (see [`templates/release-tag.md`](templates/release-tag.md)):
|
||||
|
||||
1. `git fetch <remote> --prune`.
|
||||
|
||||
@@ -13,14 +13,9 @@ Rules (llm-project-workflow):
|
||||
- If the PR is closed but `merged=false`, STOP and run reconciliation. Do not clean up.
|
||||
|
||||
Steps:
|
||||
1. Identity Checklist: Before claiming/working on merge, verify and state:
|
||||
- Required identity/profile for this task: merger (allowed to merge PRs)
|
||||
- Current authenticated identity (from whoami): <username>
|
||||
- Target task role: merger identity (must NOT be the PR author)
|
||||
*If the current identity does not match the required role (or is the PR author), STOP. Relaunch/switch to the correct profile first.*
|
||||
2. Verify authenticated identity + active profile.
|
||||
3. Confirm PR #<pr>: author (not you), state open, mergeable, review approved. Check if PR body uses `Closes #N` or `Fixes #N`; if it uses `Implements #N` or `Refs #N`, manual closing will be needed in step 29.
|
||||
4. If any gate fails → STOP and report.
|
||||
1. Verify authenticated identity + active profile.
|
||||
2. Confirm PR #<pr>: author (not you), state open, mergeable, review approved.
|
||||
3. If any gate fails → STOP and report.
|
||||
4. Merge with explicit confirmation (e.g. confirmation="MERGE PR <pr>"),
|
||||
optionally pinning the reviewed head SHA / changed-file set.
|
||||
5. Confirm remote master now contains the merge commit.
|
||||
|
||||
@@ -8,36 +8,19 @@ Task: review PR #<pr> for issue #<n>.
|
||||
Rules (llm-project-workflow):
|
||||
- Review in a SEPARATE detached review worktree, never the author's folder.
|
||||
- You must NOT be the PR author. If the authenticated user == PR author, stop.
|
||||
A different LLM-Agent-SHA does NOT make you a different actor — only a
|
||||
different authenticated Gitea user does (docs/llm-agent-sha.md).
|
||||
- Do not merge if any check fails.
|
||||
|
||||
Steps:
|
||||
1. Identity Checklist: Before claiming/working on review, verify and state:
|
||||
- Required identity/profile for this task: reviewer (allowed to review/approve/request_changes)
|
||||
- Current authenticated identity (from whoami): <username>
|
||||
- Target task role: reviewer identity (must NOT be the PR author)
|
||||
*If the current identity does not match the required role (or is the PR author), STOP. Relaunch/switch to the correct profile first.*
|
||||
2. Verify your authenticated identity (whoami) and the active profile.
|
||||
3. Fetch the PR facts: PR author, head SHA, state (must be open), base branch.
|
||||
4. If authenticated user == PR author → STOP (no self-review).
|
||||
1. Verify your authenticated identity (whoami) and the active profile.
|
||||
2. Fetch the PR facts: PR author, head SHA, state (must be open), base branch.
|
||||
3. If authenticated user == PR author → STOP (no self-review).
|
||||
4. scripts/worktree-review <pr-head-branch> # detached, branches/review-*
|
||||
cd branches/review-<pr-head-branch-slug>
|
||||
5. Confirm the worktree is clean. Inspect the FULL diff; confirm scope matches
|
||||
issue #<n>; flag any unrelated files, secrets, or formatting churn. Check that the PR body correctly uses Gitea-closing keywords (`Closes #N` or `Fixes #N`) instead of non-closing ones (`Implements #N`, `Refs #N`).
|
||||
issue #<n>; flag any unrelated files, secrets, or formatting churn.
|
||||
6. Run the test suite; note results.
|
||||
7. Post the review verdict: approve only if scope is clean and checks pass;
|
||||
otherwise request changes with specifics. Never merge from this review step.
|
||||
Include a "Review Metadata" block (attribution only — docs/llm-agent-sha.md):
|
||||
|
||||
Review Metadata:
|
||||
- LLM-Agent-SHA: llm-<12 lowercase hex, e.g. llm-41d0e7aa9f2c>
|
||||
- LLM-Role: reviewer
|
||||
- Authenticated-Gitea-User: <whoami result>
|
||||
- MCP-Profile: <profile name>
|
||||
- Eligibility: passed/failed
|
||||
|
||||
Handoff: reviewer identity, PR author, scope verdict, checks + results, decision —
|
||||
formatted as the Controller Handoff Summary (SKILL.md §K); if you could not
|
||||
merge, name the exact gate that blocked it.
|
||||
Handoff: reviewer identity, PR author, scope verdict, checks + results, decision.
|
||||
```
|
||||
|
||||
@@ -13,14 +13,9 @@ Rules (llm-project-workflow):
|
||||
- Do not self-review or self-merge.
|
||||
|
||||
Steps:
|
||||
1. Identity Checklist: Before claiming work, verify and state:
|
||||
- Required identity/profile for this task: author (allowed to push branches / create PRs)
|
||||
- Current authenticated identity (from whoami): <username>
|
||||
- Target task role: author/work identity
|
||||
*If the current identity does not match the required role (or lacks push/PR permissions), STOP before claiming the issue. Relaunch/switch to the correct profile first.*
|
||||
2. Verify the orchestration checkout is the right repo and clean.
|
||||
3. git fetch <remote> --prune; confirm local master == <remote>/master (0 0).
|
||||
4. Create the issue "<title>" (problem, scope, acceptance) and claim it
|
||||
1. Verify the orchestration checkout is the right repo and clean.
|
||||
2. git fetch <remote> --prune; confirm local master == <remote>/master (0 0).
|
||||
3. Create the issue "<title>" (problem, scope, acceptance) and claim it
|
||||
(status:in-progress + a "starting work" comment naming the branch).
|
||||
4. scripts/worktree-start <type>/issue-<n>-<slug> # type = fix|feat|docs
|
||||
cd branches/<type>-issue-<n>-<slug>
|
||||
@@ -28,21 +23,7 @@ Steps:
|
||||
6. Checks: run the test suite, compile/lint changed files, git diff --check,
|
||||
and scan the diff for secrets.
|
||||
7. Commit (issue-linked message), push the branch, open a PR to master.
|
||||
*The PR body MUST use closing keywords like `Closes #N` or `Fixes #N` to close the issue; do NOT use `Implements #N` or `Refs #N` for closing, as Gitea will not auto-close it.*
|
||||
Include an "LLM Handoff Metadata" block in the PR body (attribution only;
|
||||
never an eligibility input — docs/llm-agent-sha.md):
|
||||
|
||||
LLM Handoff Metadata:
|
||||
- LLM-Agent-SHA: llm-<12 lowercase hex, e.g. llm-8f3a9c2d6b41>
|
||||
- LLM-Role: implementer
|
||||
- Authenticated-Gitea-User: <whoami result>
|
||||
- MCP-Profile: <profile name>
|
||||
- Branch: <branch>
|
||||
- Worktree: <worktree path>
|
||||
- Self-review allowed: no
|
||||
8. Stop before review/merge — you are the author.
|
||||
|
||||
Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL —
|
||||
formatted as the Controller Handoff Summary (SKILL.md §K); end with
|
||||
"Review needed — PR is open".
|
||||
Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL.
|
||||
```
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Opt-in Gitea Integration Tests (#66)
|
||||
|
||||
Real-Gitea integration tests for the shared API client
|
||||
(`gitea_auth.api_request` / `api_get_all`). **Skipped by default** — the unit
|
||||
suite (`pytest tests/ -q`) stays fast, mocked, and network-free.
|
||||
|
||||
## What they prove
|
||||
|
||||
Against a real, disposable Gitea instance:
|
||||
|
||||
- issue listing + pagination (multi-page walk, overall `limit`)
|
||||
- PR listing through the same paginated client
|
||||
- targeted label add/remove (one label removed, others untouched)
|
||||
- permission denial fails closed (bad token → clear `401` error, token never echoed)
|
||||
- real Gitea error payloads surface as safe, redacted `RuntimeError`s
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `GITEA_INTEGRATION=1` | opt-in switch — the suite is skipped without it |
|
||||
| `GITEA_INTEGRATION_URL` | base URL (default `http://localhost:3003`) |
|
||||
| `GITEA_INTEGRATION_TOKEN` | API token for the **local test** instance |
|
||||
|
||||
Never point these at a production Gitea and never use production tokens. The
|
||||
token is used only in the `Authorization` header; tests assert it does not
|
||||
appear in any error output.
|
||||
|
||||
## Quick start (Docker)
|
||||
|
||||
```bash
|
||||
tests/integration/gitea-integration up
|
||||
export GITEA_INTEGRATION_TOKEN="$(tests/integration/gitea-integration token)"
|
||||
GITEA_INTEGRATION=1 ./venv/bin/python -m pytest tests/integration/ -q
|
||||
tests/integration/gitea-integration down
|
||||
```
|
||||
|
||||
- Image is **pinned** (`gitea/gitea:1.22.6` in `docker-compose.yml`); bump the
|
||||
pin deliberately, never `:latest`.
|
||||
- `up` waits until `/api/v1/version` answers (60s timeout).
|
||||
- `token` idempotently creates a TEST-ONLY admin (`inttest-admin`) inside the
|
||||
container and prints a fresh API token to stdout — nothing is written to disk.
|
||||
- `down` removes the container **and its volume** (full teardown).
|
||||
|
||||
An existing local Gitea works too: set `GITEA_INTEGRATION_URL` and a token for
|
||||
any account allowed to create/delete its own repos.
|
||||
|
||||
## Seed data and cleanup
|
||||
|
||||
- Each session creates one uniquely-named repo (`inttest-<8 hex>`), seeds
|
||||
issues/labels/one PR inside it, and deletes the repo on teardown
|
||||
(best-effort; a leaked repo is disposable and obvious).
|
||||
- Nothing outside the seed repo is touched; the suite never mutates
|
||||
pre-existing repos, users, or instance settings.
|
||||
|
||||
## Relationship to the unit suite
|
||||
|
||||
Unit tests remain the default and must stay mocked. Add an integration test
|
||||
only for behavior that genuinely depends on a real server (pagination
|
||||
metadata, permission semantics, live error payloads).
|
||||
@@ -1,65 +0,0 @@
|
||||
"""Fixtures for the opt-in Docker/local Gitea integration suite (#66).
|
||||
|
||||
Everything here is inert unless GITEA_INTEGRATION=1 — the test modules carry
|
||||
a module-level skipif, so a default ``pytest tests/ -q`` run never touches the
|
||||
network and never needs Docker.
|
||||
|
||||
Required environment (see tests/integration/README.md):
|
||||
- GITEA_INTEGRATION=1 opt-in switch
|
||||
- GITEA_INTEGRATION_URL base URL (default http://localhost:3003)
|
||||
- GITEA_INTEGRATION_TOKEN API token for the *local test* instance
|
||||
|
||||
The token is a throwaway credential for the disposable container. It is never
|
||||
printed, logged, or asserted on. Production credentials must never be used.
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
import uuid
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
|
||||
|
||||
from gitea_auth import api_request # noqa: E402
|
||||
|
||||
ENABLED = os.environ.get("GITEA_INTEGRATION") == "1"
|
||||
|
||||
|
||||
def _base_url():
|
||||
return os.environ.get("GITEA_INTEGRATION_URL", "http://localhost:3003").rstrip("/")
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def gitea():
|
||||
"""Session facts: base URL, auth header string, authenticated login."""
|
||||
token = os.environ.get("GITEA_INTEGRATION_TOKEN")
|
||||
if not token:
|
||||
pytest.fail(
|
||||
"GITEA_INTEGRATION=1 but GITEA_INTEGRATION_TOKEN is unset; "
|
||||
"run tests/integration/gitea-integration token"
|
||||
)
|
||||
base = _base_url()
|
||||
auth = f"token {token}"
|
||||
me = api_request("GET", f"{base}/api/v1/user", auth)
|
||||
return {"base": base, "auth": auth, "login": me["login"]}
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def seed_repo(gitea):
|
||||
"""Create a disposable, uniquely-named repo; delete it on teardown."""
|
||||
name = f"inttest-{uuid.uuid4().hex[:8]}"
|
||||
repo = api_request(
|
||||
"POST", f"{gitea['base']}/api/v1/user/repos", gitea["auth"],
|
||||
payload={"name": name, "auto_init": True,
|
||||
"description": "gitea-tools #66 integration seed (disposable)"},
|
||||
)
|
||||
owner = repo["owner"]["login"]
|
||||
yield {"owner": owner, "name": name,
|
||||
"api": f"{gitea['base']}/api/v1/repos/{owner}/{name}"}
|
||||
# Teardown: best-effort delete; a leaked repo is visible and disposable.
|
||||
try:
|
||||
api_request("DELETE", f"{gitea['base']}/api/v1/repos/{owner}/{name}",
|
||||
gitea["auth"])
|
||||
except RuntimeError:
|
||||
pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# Disposable Gitea for the opt-in integration suite (#66).
|
||||
# Pinned image for reproducibility — bump deliberately, never use :latest.
|
||||
# Usage: tests/integration/gitea-integration up|token|down
|
||||
services:
|
||||
gitea:
|
||||
image: gitea/gitea:1.22.6
|
||||
container_name: gitea-tools-integration
|
||||
environment:
|
||||
- GITEA__security__INSTALL_LOCK=true
|
||||
- GITEA__server__ROOT_URL=http://localhost:3003/
|
||||
- GITEA__server__HTTP_PORT=3000
|
||||
- GITEA__service__DISABLE_REGISTRATION=true
|
||||
- GITEA__log__LEVEL=Warn
|
||||
ports:
|
||||
- "3003:3000"
|
||||
volumes:
|
||||
- gitea-integration-data:/data
|
||||
volumes:
|
||||
gitea-integration-data:
|
||||
@@ -1,59 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# gitea-integration — manage the disposable Gitea container for the opt-in
|
||||
# integration suite (#66). See tests/integration/README.md.
|
||||
#
|
||||
# tests/integration/gitea-integration up start pinned Gitea, wait ready
|
||||
# tests/integration/gitea-integration token create test admin + print token
|
||||
# tests/integration/gitea-integration down stop container, delete volume
|
||||
#
|
||||
# The admin credentials below are TEST-ONLY, for the throwaway local container
|
||||
# started by this script. They are not secrets and must never be reused for a
|
||||
# real instance. The generated API token is printed ONCE to stdout (for
|
||||
# `export GITEA_INTEGRATION_TOKEN=$(...)`) and is never written to any file.
|
||||
|
||||
here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
compose() { docker compose -f "$here/docker-compose.yml" "$@"; }
|
||||
|
||||
base_url="${GITEA_INTEGRATION_URL:-http://localhost:3003}"
|
||||
admin_user="inttest-admin"
|
||||
admin_pass="inttest-local-only-pass" # TEST-ONLY, disposable container
|
||||
admin_email="inttest-admin@example.invalid"
|
||||
|
||||
case "${1:-}" in
|
||||
up)
|
||||
compose up -d
|
||||
printf 'gitea-integration: waiting for %s ' "$base_url"
|
||||
for _ in $(seq 1 60); do
|
||||
if curl -fsS "$base_url/api/v1/version" >/dev/null 2>&1; then
|
||||
printf '\ngitea-integration: ready\n'
|
||||
exit 0
|
||||
fi
|
||||
printf '.'
|
||||
sleep 1
|
||||
done
|
||||
printf '\ngitea-integration: Gitea did not become ready in 60s\n' >&2
|
||||
exit 1
|
||||
;;
|
||||
token)
|
||||
# Idempotent admin creation (ignore "already exists").
|
||||
compose exec -T -u git gitea gitea admin user create \
|
||||
--username "$admin_user" --password "$admin_pass" \
|
||||
--email "$admin_email" --admin --must-change-password=false \
|
||||
>/dev/null 2>&1 || true
|
||||
# Unique token name per call; Gitea prints the token as the last field.
|
||||
tok_name="inttest-$(date +%s)"
|
||||
out="$(compose exec -T -u git gitea gitea admin user generate-access-token \
|
||||
--username "$admin_user" --scopes all --token-name "$tok_name")"
|
||||
printf '%s\n' "$out" | sed -n 's/.*successfully created[:!]* *//p' | tr -d '[:space:]'
|
||||
printf '\n'
|
||||
;;
|
||||
down)
|
||||
compose down -v
|
||||
;;
|
||||
*)
|
||||
printf 'usage: tests/integration/gitea-integration up|token|down\n' >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
@@ -1,115 +0,0 @@
|
||||
"""Opt-in integration tests against a real (containerized) Gitea (#66).
|
||||
|
||||
Skipped by default. Enable with GITEA_INTEGRATION=1 plus a local instance and
|
||||
token — see tests/integration/README.md. These prove real Gitea behavior that
|
||||
the mocked unit suite can only simulate: pagination, targeted label edits,
|
||||
permission fail-closed, and error payload surfacing — all through the shared
|
||||
client (``gitea_auth.api_request`` / ``api_get_all``, #65/#67 shape).
|
||||
|
||||
No production credentials; tokens never appear in output or assertions.
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
|
||||
|
||||
from gitea_auth import api_request, api_get_all # noqa: E402
|
||||
|
||||
pytestmark = pytest.mark.skipif(
|
||||
os.environ.get("GITEA_INTEGRATION") != "1",
|
||||
reason="integration tests are opt-in: set GITEA_INTEGRATION=1 (see tests/integration/README.md)",
|
||||
)
|
||||
|
||||
|
||||
# --- issue listing + pagination --------------------------------------------
|
||||
|
||||
N_ISSUES = 7 # > page_size below, forcing a real multi-page walk
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def issues(gitea, seed_repo):
|
||||
created = []
|
||||
for i in range(N_ISSUES):
|
||||
created.append(api_request(
|
||||
"POST", f"{seed_repo['api']}/issues", gitea["auth"],
|
||||
payload={"title": f"pagination seed {i}"}))
|
||||
return created
|
||||
|
||||
|
||||
def test_issue_pagination_walks_all_pages(gitea, seed_repo, issues):
|
||||
got = api_get_all(f"{seed_repo['api']}/issues?state=open", gitea["auth"],
|
||||
page_size=3)
|
||||
titles = {i["title"] for i in got}
|
||||
assert {f"pagination seed {i}" for i in range(N_ISSUES)} <= titles
|
||||
assert len(got) >= N_ISSUES
|
||||
|
||||
|
||||
def test_issue_pagination_honors_overall_limit(gitea, seed_repo, issues):
|
||||
got = api_get_all(f"{seed_repo['api']}/issues?state=open", gitea["auth"],
|
||||
page_size=3, limit=4)
|
||||
assert len(got) == 4
|
||||
|
||||
|
||||
# --- PR listing --------------------------------------------------------------
|
||||
|
||||
def test_pr_listing_via_shared_client(gitea, seed_repo, issues):
|
||||
# Create a branch (via the contents API) and a real PR, then list.
|
||||
api_request(
|
||||
"POST", f"{seed_repo['api']}/contents/inttest.txt", gitea["auth"],
|
||||
payload={"content": "aW50ZWdyYXRpb24gc2VlZAo=", # "integration seed"
|
||||
"message": "seed PR branch", "new_branch": "inttest-pr"})
|
||||
pr = api_request(
|
||||
"POST", f"{seed_repo['api']}/pulls", gitea["auth"],
|
||||
payload={"title": "integration seed PR", "head": "inttest-pr",
|
||||
"base": "main"})
|
||||
got = api_get_all(f"{seed_repo['api']}/pulls?state=open", gitea["auth"],
|
||||
page_size=1)
|
||||
assert any(p["number"] == pr["number"] for p in got)
|
||||
|
||||
|
||||
# --- targeted label add/remove ----------------------------------------------
|
||||
|
||||
def test_targeted_label_add_and_remove(gitea, seed_repo, issues):
|
||||
labels = {}
|
||||
for name, color in (("keep-me", "#00ff00"), ("drop-me", "#ff0000")):
|
||||
labels[name] = api_request(
|
||||
"POST", f"{seed_repo['api']}/labels", gitea["auth"],
|
||||
payload={"name": name, "color": color})
|
||||
issue_no = issues[0]["number"]
|
||||
issue_labels_url = f"{seed_repo['api']}/issues/{issue_no}/labels"
|
||||
api_request("POST", issue_labels_url, gitea["auth"],
|
||||
payload={"labels": [labels["keep-me"]["id"],
|
||||
labels["drop-me"]["id"]]})
|
||||
# Targeted removal of one label must not disturb the other.
|
||||
api_request("DELETE", f"{issue_labels_url}/{labels['drop-me']['id']}",
|
||||
gitea["auth"])
|
||||
remaining = {l["name"] for l in api_request("GET", issue_labels_url,
|
||||
gitea["auth"])}
|
||||
assert "keep-me" in remaining
|
||||
assert "drop-me" not in remaining
|
||||
|
||||
|
||||
# --- permission denial / fail-closed -----------------------------------------
|
||||
|
||||
def test_bad_token_fails_closed_without_leaking_it(gitea):
|
||||
bogus = "token 0123456789abcdef0123456789abcdef01234567"
|
||||
with pytest.raises(RuntimeError) as exc:
|
||||
api_request("GET", f"{gitea['base']}/api/v1/user", bogus)
|
||||
msg = str(exc.value)
|
||||
assert "401" in msg
|
||||
assert "0123456789abcdef" not in msg # credential never echoed
|
||||
|
||||
|
||||
def test_real_error_payload_surfaces_safely(gitea, seed_repo):
|
||||
# A genuinely missing resource: Gitea's real 404 error payload must become
|
||||
# a clear RuntimeError, not a stack trace, and must not echo the token.
|
||||
with pytest.raises(RuntimeError) as exc:
|
||||
api_request("GET", f"{seed_repo['api']}/issues/999999", gitea["auth"])
|
||||
msg = str(exc.value)
|
||||
assert "404" in msg
|
||||
token = os.environ.get("GITEA_INTEGRATION_TOKEN", "")
|
||||
if token:
|
||||
assert token not in msg
|
||||
@@ -1,195 +0,0 @@
|
||||
"""Negative tests for LLM-Agent-SHA attribution (#86, Phase 0).
|
||||
|
||||
``LLM-Agent-SHA`` (docs/llm-agent-sha.md) is attribution metadata ONLY. These
|
||||
tests prove it can never bypass the review/merge safety gates:
|
||||
|
||||
1. Same Gitea user + different LLM-Agent-SHA still fails self-review/approval.
|
||||
2. Same Gitea user + different LLM-Agent-SHA still fails self-merge.
|
||||
3. The eligibility logic does not consult SHA metadata at all — results are
|
||||
identical with no SHA, one SHA, or a different SHA in the environment, and
|
||||
no gate accepts an agent-SHA input.
|
||||
|
||||
Phase 0 adds no SHA support to any MCP tool; the environment variables set
|
||||
here (``LLM_AGENT_SHA`` / ``LLM_AGENT_ROLE``) simulate a future launcher and
|
||||
must be ignored by every gate.
|
||||
"""
|
||||
import inspect
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
|
||||
|
||||
from mcp_server import ( # noqa: E402
|
||||
gitea_check_pr_eligibility,
|
||||
gitea_merge_pr,
|
||||
gitea_review_pr,
|
||||
gitea_submit_pr_review,
|
||||
)
|
||||
|
||||
FAKE_AUTH = "Basic dGVzdDp0ZXN0"
|
||||
SHA_PATTERN = re.compile(r"^llm-[0-9a-f]{12}$")
|
||||
# Two distinct, well-formed agent SHAs "belonging" to the same Gitea user.
|
||||
SHA_IMPLEMENTER = "llm-8f3a9c2d6b41"
|
||||
SHA_WOULD_BE_REVIEWER = "llm-41d0e7aa9f2c"
|
||||
|
||||
|
||||
def _pr(author, state="open", sha="abc123", mergeable=True):
|
||||
return {
|
||||
"user": {"login": author},
|
||||
"state": state,
|
||||
"head": {"sha": sha},
|
||||
"mergeable": mergeable,
|
||||
}
|
||||
|
||||
|
||||
class TestShaFormatConvention(unittest.TestCase):
|
||||
"""The documented format: llm-<12 lowercase hex>, nothing identifying."""
|
||||
|
||||
def test_documented_examples_are_valid(self):
|
||||
for value in (SHA_IMPLEMENTER, SHA_WOULD_BE_REVIEWER, "llm-b7c93d441a08"):
|
||||
self.assertRegex(value, SHA_PATTERN)
|
||||
|
||||
def test_identifying_or_malformed_values_are_rejected(self):
|
||||
for bad in (
|
||||
"llm-8F3A9C2D6B41", # uppercase
|
||||
"llm-8f3a9c2d6b4", # too short
|
||||
"llm-8f3a9c2d6b411", # too long
|
||||
"llm-opus4", # model name, not hex
|
||||
"claude-8f3a9c2d6b41", # provider prefix
|
||||
"jcwalker3", # username
|
||||
"llm-user@example.com", # email
|
||||
"8f3a9c2d6b41", # missing prefix
|
||||
"",
|
||||
):
|
||||
self.assertNotRegex(bad, SHA_PATTERN)
|
||||
|
||||
|
||||
class TestShaCannotBypassSelfReview(unittest.TestCase):
|
||||
"""Scenario: user A (SHA 1) authored the PR; user A (SHA 2) tries to act."""
|
||||
|
||||
def _env(self, agent_sha, role):
|
||||
# Reviewer-capable profile + a simulated launcher-injected agent SHA.
|
||||
return {
|
||||
"GITEA_PROFILE_NAME": "gitea-reviewer",
|
||||
"GITEA_ALLOWED_OPERATIONS": "read,review,approve,merge",
|
||||
"LLM_AGENT_SHA": agent_sha,
|
||||
"LLM_AGENT_ROLE": role,
|
||||
}
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_same_user_different_sha_cannot_approve(self, _auth, mock_api):
|
||||
mock_api.side_effect = [{"login": "jcwalker3"}, _pr("jcwalker3")]
|
||||
env = self._env(SHA_WOULD_BE_REVIEWER, "reviewer")
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_check_pr_eligibility(pr_number=9, action="approve", remote="prgs")
|
||||
self.assertFalse(r["eligible"])
|
||||
self.assertIn("authenticated user is PR author", r["reasons"])
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_same_user_different_sha_cannot_merge(self, _auth, mock_api):
|
||||
mock_api.side_effect = [{"login": "jcwalker3"}, _pr("jcwalker3")]
|
||||
env = self._env(SHA_WOULD_BE_REVIEWER, "merger")
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_check_pr_eligibility(pr_number=9, action="merge", remote="prgs")
|
||||
self.assertFalse(r["eligible"])
|
||||
self.assertIn("authenticated user is PR author", r["reasons"])
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_gated_merge_tool_refuses_self_merge_despite_sha(self, _auth, mock_api):
|
||||
# Even the fully-confirmed gated merge path must refuse: correct
|
||||
# confirmation string, mergeable PR, merge-capable profile — but the
|
||||
# authenticated user is the PR author, whatever the agent SHA says.
|
||||
mock_api.side_effect = [{"login": "jcwalker3"}, _pr("jcwalker3")]
|
||||
env = self._env(SHA_WOULD_BE_REVIEWER, "merger")
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_merge_pr(
|
||||
pr_number=9, confirmation="MERGE PR 9", remote="prgs")
|
||||
self.assertFalse(r.get("performed"))
|
||||
for call in mock_api.call_args_list:
|
||||
method, url = call.args[0], call.args[1]
|
||||
self.assertFalse(
|
||||
method == "POST" and url.endswith("/merge"),
|
||||
f"self-merge mutation reached the API: {method} {url}",
|
||||
)
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_review_tool_refuses_self_approval_despite_sha(self, _auth, mock_api):
|
||||
mock_api.side_effect = [{"login": "jcwalker3"}, _pr("jcwalker3")]
|
||||
env = self._env(SHA_WOULD_BE_REVIEWER, "reviewer")
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_review_pr(
|
||||
pr_number=9, event="APPROVE", body="self approve", merge=False,
|
||||
remote="prgs")
|
||||
self.assertFalse(r["success"])
|
||||
self.assertIn("authenticated user is PR author", r["message"])
|
||||
for call in mock_api.call_args_list:
|
||||
method, url = call.args[0], call.args[1]
|
||||
self.assertFalse(
|
||||
method == "POST" and url.endswith("/reviews"),
|
||||
f"self-review mutation reached the API: {method} {url}",
|
||||
)
|
||||
|
||||
|
||||
class TestEligibilityNeverConsultsSha(unittest.TestCase):
|
||||
"""The gates have no SHA input: not via env, not via parameters."""
|
||||
|
||||
def _run_eligibility(self, extra_env):
|
||||
env = {
|
||||
"GITEA_PROFILE_NAME": "gitea-reviewer",
|
||||
"GITEA_ALLOWED_OPERATIONS": "read,review,approve",
|
||||
}
|
||||
env.update(extra_env)
|
||||
with patch("mcp_server.get_auth_header", return_value=FAKE_AUTH), \
|
||||
patch("mcp_server.api_request") as mock_api:
|
||||
mock_api.side_effect = [{"login": "reviewer-bot"}, _pr("author-bot")]
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
return gitea_check_pr_eligibility(
|
||||
pr_number=5, action="approve", remote="prgs")
|
||||
|
||||
def test_result_identical_with_without_and_across_shas(self):
|
||||
baseline = self._run_eligibility({})
|
||||
with_one = self._run_eligibility(
|
||||
{"LLM_AGENT_SHA": SHA_IMPLEMENTER, "LLM_AGENT_ROLE": "implementer"})
|
||||
with_other = self._run_eligibility(
|
||||
{"LLM_AGENT_SHA": SHA_WOULD_BE_REVIEWER, "LLM_AGENT_ROLE": "reviewer"})
|
||||
self.assertEqual(baseline, with_one)
|
||||
self.assertEqual(baseline, with_other)
|
||||
self.assertTrue(baseline["eligible"]) # sanity: a real decision ran
|
||||
|
||||
def test_eligibility_result_carries_no_agent_sha(self):
|
||||
r = self._run_eligibility(
|
||||
{"LLM_AGENT_SHA": SHA_IMPLEMENTER, "LLM_AGENT_ROLE": "implementer"})
|
||||
blob = repr(r)
|
||||
self.assertNotIn(SHA_IMPLEMENTER, blob)
|
||||
self.assertNotIn("LLM_AGENT", blob)
|
||||
|
||||
def test_gate_functions_accept_no_agent_sha_parameter(self):
|
||||
for fn in (gitea_check_pr_eligibility, gitea_merge_pr,
|
||||
gitea_review_pr, gitea_submit_pr_review):
|
||||
for param in inspect.signature(fn).parameters:
|
||||
lowered = param.lower()
|
||||
self.assertNotIn("agent", lowered,
|
||||
f"{fn.__name__} accepts agent param {param!r}")
|
||||
self.assertNotIn("llm", lowered,
|
||||
f"{fn.__name__} accepts llm param {param!r}")
|
||||
|
||||
def test_gate_sources_never_read_agent_sha(self):
|
||||
# Phase 0 guarantee: no gate reads LLM_AGENT_* metadata at all.
|
||||
for fn in (gitea_check_pr_eligibility, gitea_merge_pr,
|
||||
gitea_review_pr, gitea_submit_pr_review):
|
||||
src = inspect.getsource(fn)
|
||||
self.assertNotIn("LLM_AGENT", src,
|
||||
f"{fn.__name__} reads LLM_AGENT metadata")
|
||||
self.assertNotIn("agent_sha", src,
|
||||
f"{fn.__name__} consults an agent SHA")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -370,55 +370,6 @@ class TestMergePR(unittest.TestCase):
|
||||
expected_changed_files=["b.py", "a.py"], remote="prgs")
|
||||
self.assertTrue(r["performed"])
|
||||
|
||||
# -- read-back / cleanup surfacing (#98) -----------------------------------
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_readback_failure_reports_skipped_cleanup(self, _auth, mock_api):
|
||||
"""Merge OK + read-back GET failure => explicit cleanup skip, not silence."""
|
||||
mock_api.side_effect = [
|
||||
{"login": "merger-bot"}, self._pr("author-bot"),
|
||||
{}, # merge POST
|
||||
RuntimeError("HTTP 502: Gitea upstream unavailable"), # read-back fails
|
||||
]
|
||||
env = {"GITEA_PROFILE_NAME": "gitea-merger",
|
||||
"GITEA_ALLOWED_OPERATIONS": "read,merge"}
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_merge_pr(pr_number=8, confirmation=self._confirm(8),
|
||||
remote="prgs")
|
||||
# The merge itself is still reported performed/successful.
|
||||
self.assertTrue(r["performed"])
|
||||
self.assertEqual(r["merge_result"], "PR #8 merged via 'merge'.")
|
||||
self.assertIsNone(r["merge_commit"])
|
||||
# The skip is explicit, not silent.
|
||||
self.assertEqual(r["cleanup_status"], "skipped (merge read-back failed)")
|
||||
# No tracker-cleanup API traffic after the failed read-back:
|
||||
# user, PR (eligibility), merge POST, read-back — and nothing more.
|
||||
self.assertEqual(mock_api.call_count, 4)
|
||||
for c in mock_api.call_args_list:
|
||||
self.assertNotEqual(c.args[0], "DELETE")
|
||||
|
||||
@patch("mcp_server.cleanup_in_progress_for_pr",
|
||||
side_effect=RuntimeError("boom token secret-xyz"))
|
||||
@patch("mcp_server.api_request")
|
||||
@patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
|
||||
def test_cleanup_exception_surfaced_and_redacted(self, _auth, mock_api, _cleanup):
|
||||
"""Unexpected cleanup exception => merge still succeeds; error surfaced redacted."""
|
||||
mock_api.side_effect = [
|
||||
{"login": "merger-bot"}, self._pr("author-bot"),
|
||||
{}, # merge POST
|
||||
{"merged_commit_sha": "c9"}, # read-back OK
|
||||
]
|
||||
env = {"GITEA_PROFILE_NAME": "gitea-merger",
|
||||
"GITEA_ALLOWED_OPERATIONS": "read,merge"}
|
||||
with patch.dict(os.environ, env, clear=True):
|
||||
r = gitea_merge_pr(pr_number=8, confirmation=self._confirm(8),
|
||||
remote="prgs")
|
||||
self.assertTrue(r["performed"])
|
||||
self.assertEqual(r["merge_commit"], "c9")
|
||||
self.assertTrue(r["cleanup_status"].startswith("skipped (cleanup error:"))
|
||||
self.assertNotIn("secret-xyz", r["cleanup_status"])
|
||||
|
||||
# -- confirmation ---------------------------------------------------------
|
||||
|
||||
@patch("mcp_server.api_request")
|
||||
@@ -1649,23 +1600,3 @@ class TestTrackerHygieneCleanup(unittest.TestCase):
|
||||
res = gitea_close_issue(issue_number=1)
|
||||
self.assertTrue(res["success"])
|
||||
self.assertIn("error:", res["cleanup_status"].get(1))
|
||||
|
||||
def test_extract_linked_issue_numbers_hygiene(self):
|
||||
from mcp_server import extract_linked_issue_numbers
|
||||
# Standard closing keywords
|
||||
self.assertEqual(extract_linked_issue_numbers("Closes #123"), [123])
|
||||
self.assertEqual(extract_linked_issue_numbers("Fixes #123"), [123])
|
||||
self.assertEqual(extract_linked_issue_numbers("Resolves #123"), [123])
|
||||
|
||||
# New implements/implemented keywords
|
||||
self.assertEqual(extract_linked_issue_numbers("Implements #123"), [123])
|
||||
self.assertEqual(extract_linked_issue_numbers("implemented #123"), [123])
|
||||
self.assertEqual(extract_linked_issue_numbers("implement #123"), [123])
|
||||
|
||||
# refs / ref should NOT match
|
||||
self.assertEqual(extract_linked_issue_numbers("Refs #123"), [])
|
||||
self.assertEqual(extract_linked_issue_numbers("ref #123"), [])
|
||||
|
||||
# branch name fallback
|
||||
self.assertEqual(extract_linked_issue_numbers("", branch_name="issue-123"), [123])
|
||||
self.assertEqual(extract_linked_issue_numbers("", branch_name="feat/issue-123-foo"), [123])
|
||||
|
||||
Reference in New Issue
Block a user