Add docs/llm-workflow-runbooks.md — the final roadmap #10 deliverable:
operational runbooks for LLM-operated Gitea workflows, built on the shipped
canonical profiles + interactive menu + gated review/merge + audit logging.
Covers:
- Principle: the profile is the role, not the LLM (task-scoped, not assigned).
- Canonical config: GITEA_MCP_CONFIG / GITEA_MCP_PROFILE, version, profiles,
keychain + env auth references, precedence, legacy env-only fallback.
- Interactive menu (python gitea_config.py menu): create author/reviewer
profiles, generate Claude/Gemini/Codex launcher snippets, validate auth,
check PR reviewer eligibility.
- Thin-launcher pattern: LLM configs carry only command/args + the two
GITEA_MCP_* vars — never raw tokens/passwords.
- Migration away from duplicated GITEA_USER_*/GITEA_PASS_*/GITEA_SITE_* blocks;
secrets referenced by keychain id or env var name only.
- Per-workflow runbooks (create issue/children, implement+PR, review/request-
changes/approve, merge, close-after-merge, stop-on-blocker) with safe prompts.
- Fail-closed behavior table (unknown identity/profile, self-author, moved head,
unexpected files, detected secrets, production/deploy) and no self-review/merge.
Docs-only: no implementation code. Safe placeholder examples only (no real
tokens, passwords, usernames, or private config). README links the new runbook.
Closes#17. Refs #10.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add an interactive utility so users create/edit/validate canonical runtime
profiles and generate safe LLM launcher snippets without hand-editing JSON or
pasting tokens into Claude/Gemini/Codex configs.
Run: `python gitea_config.py menu` (or `python gitea_config_menu.py`).
gitea_config.py — pure, testable authoring helpers:
- is_valid_profile_name, build_profile, keychain_auth/env_auth, empty_config
- validate_config (reports missing base_url/auth, inline token/password — never
echoing the secret value)
- add_profile (preserves existing, rejects dup/invalid name/missing base_url),
upsert_profile, remove_profile
- save_config: mkdir parents + atomic temp-then-os.replace, pretty JSON
- launcher_entry: thin MCP entry (command/args + GITEA_MCP_CONFIG/PROFILE only)
- keychain_set: store a token via `security add-generic-password` (token passed
as an arg, never returned/printed/logged; injectable runner)
- `menu` __main__ dispatch
gitea_config_menu.py — interactive loop with fully injectable IO/secret/HTTP/
keychain so it is testable without a real terminal, keychain, or network:
- list / add / edit / remove / validate profiles
- test authentication + show authenticated user (calls /user only on request)
- reviewer-eligibility helper (authenticated user vs PR author, open state) —
read-only, never approves/merges
- launcher snippets for Claude / Gemini / Codex (no secrets)
Security: tokens are never written to profiles.json, launcher snippets, logs,
or errors — only keychain ids / env var names are stored. Backwards compatible:
menu is optional; env-only mode and MCP server startup are unchanged.
Tests: tests/test_config_menu.py (21 cases) — name validation, preserve-on-add,
dup/invalid/missing-field rejection, atomic write (+ replace-failure leaves the
original intact, no temp debris), keychain_set stores-without-printing, launcher
snippets secret-free, eligibility eligible/self-author/closed, and a full menu
add→list→quit flow proving the token value never reaches disk or stdout.
Stacked on #30 (canonical profiles); base branch feat/json-runtime-profiles.
Refs #10, #19. Closes#31.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework the JSON runtime-profile config from the earlier ad-hoc schema
(profiles + token_env) to the canonical single-file model in #19, so every LLM
launcher can reference one shared Gitea profiles file instead of duplicating
GITEA_USER_*/GITEA_PASS_* blocks or embedding tokens.
Canonical schema (gitea_config.py):
- top-level "version" (1) + "profiles" map.
- each profile: base_url, username, default_owner, execution_profile, and a
typed auth reference:
{ "type": "keychain", "id": "..." } -> macOS keychain (security(1))
{ "type": "env", "name": "..." } -> named environment variable
- inline "token"/"password" keys are rejected (never accepted or echoed).
- select via GITEA_MCP_CONFIG (path) + GITEA_MCP_PROFILE (name).
gitea_auth integration:
- get_profile() overlays env over the selected profile (env wins; JSON fills
the rest); profile_name <- execution_profile; token_source_name <- the
non-secret auth reference name (env var name or "keychain:<id>"); now also
surfaces username + default_owner.
- get_auth_header() resolves the profile's auth reference (env/keychain) as a
token fallback after explicit env tokens; a ConfigError there fails closed.
Security / safety:
- Secrets referenced only (keychain id / env name); token values never stored
in or returned as metadata. Errors never print file contents, tokens, or
passwords (JSONDecodeError context suppressed).
- Missing file / invalid JSON / unsupported version / unknown-or-unset profile
/ unresolvable secret reference all raise a clear, safe ConfigError.
- No network calls during config parsing; keychain lookup is on-demand and
injectable for tests.
- Backwards compatible: GITEA_MCP_CONFIG unset => legacy env-only mode
(existing get_profile/get_auth_header tests unchanged).
Docs: README canonical-profile + thin-launcher (Claude/Gemini/Codex) sections
and a migration note away from duplicated GITEA_PASS_* blocks; .env.example and
gitea-mcp.example.json updated to the canonical shape (safe placeholders only).
Tests: tests/test_config.py (31 cases) — legacy env-only, JSON selection,
multiple profiles, missing/unset profile, invalid JSON, unsupported version,
env-override precedence, keychain + env auth-reference parsing and resolution,
missing-secret errors, inline token/password redaction, and no-network parse.
Refs #10. Completes the closed#19 (env-based profiles) by adding the canonical
shared-file model. Supersedes this PR's earlier simpler JSON schema.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Let one MCP server select among named Gitea runtime profiles from a JSON file
instead of editing code or juggling many .env files:
GITEA_MCP_CONFIG=/path/to/gitea-mcp.json
GITEA_MCP_PROFILE=dev
- New gitea_config.py: load/validate the JSON, select the named profile, and
resolve its token by env-var reference. Profiles supply base_url,
profile_name, token_env, owner/repo, allowed/forbidden operations, and audit
label.
- gitea_auth.get_profile() now overlays env over the selected JSON profile:
explicit env vars win, the JSON profile fills only what env leaves unset.
- gitea_auth.get_auth_header() gains a JSON token_env fallback after explicit
env tokens (env still wins).
Security / safety:
- Tokens are referenced by env-var NAME (token_env); an inline "token" is
rejected and never echoed. The value is never stored in or returned as
profile metadata.
- Fail-safe errors: missing file / invalid JSON / unknown or unset selected
profile raise a clear ConfigError that never prints file contents or tokens
(JSONDecodeError context is suppressed so the raw file text can't surface).
- No network calls during config parsing.
- Real config files are gitignored (gitea-mcp*.json), example kept.
Backwards compatible: with GITEA_MCP_CONFIG unset, behaviour is exactly the
prior env-only behaviour (all existing get_profile/get_auth_header tests pass
unchanged).
Docs: README JSON-profiles section + env table rows, .env.example placeholders,
gitea-mcp.example.json.
Tests: tests/test_config.py (22 cases) — env-only, selection, multiple
profiles, env-override precedence, missing file, invalid JSON, missing/unset
profile, inline-token rejection + redaction, and no-network-during-parse.
Refs #10. Note: issue #19 (env-based profiles) was already implemented and
closed; this JSON-file capability is adjacent new scope tracked under the
roadmap rather than reopening #19.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add durable, opt-in audit logging for every mutating Gitea MCP action so an
operator can see which execution profile and authenticated Gitea user
performed (or was blocked from / failed) each mutation.
- New gitea_audit.py: pure, no-network module — recursive secret redaction
(token/password/authorization keys; token/Basic/Bearer value runs),
build_event (timestamp, action, result, profile, audit label, authenticated
username, repo, issue/PR, target branch, head SHA, redacted request
metadata), and an append-only JSON Lines sink.
- mcp_server.py: _audit helper + _audited context manager (simple mutations)
and an _audit_pr_result decorator (gated review/merge tools, reading their
own result dict) wired into create_issue, create_pr, edit_pr, close_issue,
commit_files, delete_branch, create_label, set_issue_labels, mark_issue
(label/unlabel), gitea_submit_pr_review, and gitea_merge_pr.
- Outcomes recorded as allowed/blocked/failed/succeeded; blocked and failed
eligibility checks are logged, not just successes.
Off by default: records are written only when GITEA_AUDIT_LOG is set. When it
is unset every audit path short-circuits — no records, no extra API calls — so
existing tool behaviour and API call sequences are unchanged. Auditing never
raises; sink writes are best-effort. Tokens are never written.
Docs: README env table + audit note, .env.example placeholder.
Tests: tests/test_audit.py (19 cases) — redaction, event build, sink writes,
per-tool success/failure/blocked records, secret-free output, off-by-default
no-op, and audit-failure-never-breaks-action.
Closes#18
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
api_request now retries HTTP 429 responses instead of failing immediately:
- Parse and honor a valid Retry-After header (seconds or HTTP-date).
- Fall back to full-jitter capped exponential backoff when the header is
missing or invalid.
- Bound retries by max_retries and delay by max_delay (env-overridable via
GITEA_MAX_RETRIES / GITEA_RETRY_BASE_DELAY / GITEA_RETRY_MAX_DELAY) — no
infinite loops.
- Non-429 errors and successful responses are unchanged.
Sleep, randomness, and clock are injectable so retry timing is tested
deterministically. Adds tests/test_retry_backoff.py (23 cases).
Closes#27
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Stale documentation only — no behavior change. The module docstring and the
--merge / --merge-method argparse help text no longer advertise a working CLI
merge. They now state CLI merge is disabled/fail-closed and that merge is
handled solely by the gated gitea_merge_pr MCP workflow (#16).
CLI merge remains disabled: --merge still fails closed with no API call, and
review_pr.py contains no /merge call. No MCP merge gate was changed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reviewer found the MCP merge surface is gated but two local CLI scripts remain
ungated merge paths that LLM automations in this project have been using.
Close them (Option B — minimal safe fix; full gated CLI merge left to a
follow-up):
- review_pr.py: `--merge` now fails closed BEFORE any API call with a clear
message directing callers to the gated `gitea_merge_pr` MCP workflow. The
review-only path is unchanged. The merge execution block was removed.
- merge_pr.py: main() is now a fail-closed no-op — reads no credentials and
makes no merge API call; prints that merge is only available via the gated
workflow.
- README: the `review_pr.py` row and Quick Examples no longer advertise a CLI
`--merge` path; added an audit-logging clarification that #16 returns
structured gate/merge results but does not add durable audit logging, which
is tracked by #18.
Tests updated/added:
- test_review_pr.py: `--merge` fails closed with no API call; message points to
the gated workflow.
- test_merge_pr.py: merge fails closed with no API call, even with
--force/--do/--title/--message; message points to the gated workflow.
- test_mcp_server.py: README no longer advertises the ungated CLI merge example.
The gated MCP `gitea_merge_pr` is unchanged and still gated; `gitea_review_pr`
still fails closed on merge=True; `gitea_submit_pr_review` still cannot merge.
No secrets, auth headers, raw env, or credential paths are exposed. No
Jenkins/Ops/GlitchTip/Release/deploy/CI behavior added. #17/#18 not started.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the ungated gitea_merge_pr with a gated merge workflow. This is now
the only merge path the MCP server exposes; the merge API is called only
after every safety gate passes.
Gates (fail-closed at each step):
1. Merge method is merge | squash | rebase.
2. Explicit confirmation: confirmation must equal "MERGE PR <n>" (without it,
zero API calls are made).
3. Reuse gitea_check_pr_eligibility (#14) with action 'merge': proves the
authenticated identity, the active profile (and that it allows merge), the
PR author, blocks self-merge, requires the PR open, and fails closed when
the PR is not mergeable or mergeability is unknown.
4. Optional expected_head_sha: refuse if the PR head moved.
5. Optional expected_changed_files: refuse if the PR's changed file set differs.
6. Redundant self-merge block (auth user == PR author).
The force/ignore-checks option was removed — Gitea's own mergeable signal
(which reflects branch-protection required reviews/checks) must be positive,
so required approval/check state is honoured, never bypassed.
Output reports performed, authenticated user, profile name, PR author, PR
number, head SHA checked, merge method, gates passed/blocked, and merge
result / merge commit — never a token, auth header, or credential. Error text
is scrubbed via _redact.
Surface audit: no ungated merge path remains. The /merge endpoint appears only
inside gitea_merge_pr; gitea_review_pr fails closed on merge=True before any
API call; gitea_submit_pr_review has no merge parameter and 'merge' is not a
reviewable action. Tests assert all three.
Tests cover: merge succeeds only when all gates pass; self-author blocked;
unknown identity/profile blocked; profile without merge permission blocked;
missing/wrong confirmation blocked (no API call); head-SHA mismatch blocked;
changed-files mismatch blocked; closed PR blocked; non-mergeable blocked;
unknown mergeability fail-closed; no merge call when gates fail; invalid merge
method rejected; output and error redaction; and the no-ungated-merge-path audit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add gitea_submit_pr_review, the only tool that submits a Gitea PR review.
It performs a review mutation (comment / approve / request_changes) only
after every safety gate passes, and never merges.
Gates (fail-closed at each step):
1. Validate action is comment | approve | request_changes.
2. Reuse gitea_check_pr_eligibility (#14) for authenticated-user lookup,
active-profile lookup, PR-author lookup, self-approval block, and the
profile-allowed-operation check. approve requires 'approve' eligibility,
request_changes requires 'request_changes', comment requires 'review'.
3. Redundant self-approval block (auth user == PR author).
4. Optional expected_head_sha: refuse if the PR head has moved.
5. Only then POST /repos/{owner}/{repo}/pulls/{n}/reviews (formal review
endpoint, so approvals/change-requests carry real review state).
Output reports action, whether performed, authenticated user, profile name,
PR author, PR number, head SHA checked, and reasons — never a token, auth
header, or credential. Error text is scrubbed via _redact as defence in depth.
Merge is intentionally not implemented (belongs to #16).
Tests cover: self-author approve blocked, approve/request_changes/comment
succeed only when eligible, unknown identity fail-closed, disallowed profile
op blocked, head-SHA mismatch blocked, no mutation when gates fail, invalid
action rejected, and secret redaction in output and error paths.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add two explicit eligibility tests requested in review of PR #24:
- self-author blocked from 'approve' (eligible=false, reason
"authenticated user is PR author").
- 'merge' fails closed when Gitea reports mergeable=None (eligible=false,
reason "PR mergeability unknown").
Tests only; no implementation change. Behavior already enforced by
gitea_check_pr_eligibility.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a read-only MCP tool that decides whether the current authenticated
identity + active runtime profile is eligible to review, approve,
request_changes, or merge a specific PR. Evaluation only — it never
reviews, approves, requests changes, merges, or mutates anything.
Inspects: authenticated username (/user), active profile metadata
(allowed/forbidden operations), and PR facts (author, state, head SHA,
mergeability). Returns {eligible, requested_action, authenticated_user,
profile_name, pr_author, pr_state, head_sha, mergeable, reasons}.
Fail-closed rules:
- unknown action / unknown remote -> not eligible
- action not in allowed ops, or in forbidden ops -> not eligible
- identity undetermined -> not eligible
- authenticated user == PR author -> cannot approve/merge
- PR not open -> not eligible
- merge requires a positive mergeable signal
No token/auth-header exposure. No review/approve/request-changes
mutation. No merge mutation. No multi-token switching. No
Jenkins/Ops/GlitchTip/Release/deploy behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a read-only MCP tool that reports the active runtime execution
profile so an LLM can inspect what the current process is configured to
do before deciding whether to attempt an action later.
- gitea_get_profile: returns profile_name, allowed/forbidden operation
categories, audit_label, token_source_name (a NAME, never a value),
base_url, remote, resolved server, and — optionally — the verified
authenticated username. Identity resolution fails soft and marks
identity_status (verified/unknown/unavailable/not_resolved); the
profile config is always returned. Never mutates Gitea.
- gitea_auth.get_profile(): extended with forbidden_operations,
audit_label, token_source_name from env (non-secret metadata).
- .env.example / README: document the new optional metadata vars and
the discovery tool.
- tests: metadata parsing, verified/unavailable/unknown identity paths,
skip-identity, and secret-redaction.
Read-only. No token exposure. No multi-token switching. No PR
eligibility, review, or merge workflow. No Jenkins/Ops/GlitchTip/
Release/deploy behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Allow the same MCP server to run as separate MCP entries, each with its
own token and profile name, so roles stay task-scoped (the profile is
the role, not the LLM).
- gitea_auth.get_profile(): reads GITEA_PROFILE_NAME,
GITEA_ALLOWED_OPERATIONS, GITEA_BASE_URL as non-secret metadata.
Never reads/returns/logs the token.
- gitea_whoami now surfaces the safe profile metadata (name + allowed
operations) alongside identity; token still never exposed.
- .env.example: placeholder-only template for a runtime profile.
- .gitignore: track .env.example while keeping real .env* ignored.
- README: document multiple env-configured MCP entries.
- tests: profile defaults/parsing, token-never-included, whoami surfaces
profile without leaking token.
One token + one profile per process. No multi-token switching in a
single runtime. No approve/merge/eligibility workflow. No
Jenkins/Ops/GlitchTip/Release/deploy behavior. No real secrets.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a read-only MCP tool that calls Gitea's authenticated-user
endpoint (GET /api/v1/user) and returns safe identity metadata only:
username, display name, user id, email, server, and remote.
This lets future review/merge workflows prove which Gitea account the
MCP server is authenticated as, so self-review/self-merge can be
detected before acting — the blocker discovered during PR #8 dogfooding.
- Never returns the token, Authorization header, password, or secrets.
- Fails closed with a clear error if identity cannot be determined.
- No mutation; no profile switching; no review/approve/merge behavior.
Tests: identity mapping, secret-redaction, fail-closed, unknown-remote.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address reviewer blockers on PR #8:
- Remove trailing whitespace in credential-isolation.md and release-workflows.md
- Add approved naming coverage (MCP Control Plane / mcp-control-plane project
and repo names; common, gitea-mcp, jenkins-mcp, ops-mcp, release-mcp packages)
to tool-boundaries.md
Documentation-only. No code, scaffolding, or config changes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- mirror_refs.sh: additive branch+tag mirroring between dadeschools (HTTPS)
and prgs (SSH:2222). Dry-run default, --apply to execute, --force for
diverged branches. Uses bare repo cache for isolation.
- test_mirror_refs.py: flag parsing, safety defaults, brace-delimited refspec
validation, and local bare-repo integration tests (FF detection, branch/tag
comparison).
- README.md: document mirror_refs.sh, test suite, and multi-instance auth.
- argparse: --remote {dadeschools,prgs}, --title/--head/--base/--body,
--body-file (or '-' for stdin), and --host/--org/--repo overrides.
- REMOTES table: dadeschools (gitea.dadeschools.net/Contractor) and
prgs (gitea.prgs.cc/Scaled-Tech-Consulting).
- Print 'PR #N: <url>' on success; surface API error body on failure.
- Fix credential parsing to split('=', 1) so tokens containing '=' work.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sysadmin
jcwalker3