docs: Jenkins read-only build status tools design (#72) #88

2026-07-02T13:34:40-05:00

jcwalker3 commented

2026-07-02 13:34:40 -05:00

Implements #72. Design documentation only — no implementation, no code changes, no Jenkins code in mcp_server.py.

Adds docs/architecture/jenkins-readonly-build-status-design.md (alongside ADR-0001).

What it covers (per #72 acceptance criteria)

Minimum read-only tool set: jenkins_whoami, jenkins_list_jobs, jenkins_latest_build, jenkins_build_status, jenkins_get_build, optional approval-gated jenkins_console_tail. All GET-only.
Latest build status + safe field allowlist: build URL, number, branch, timestamp, duration, result (null+building → IN_PROGRESS), best-effort commit SHA. No raw payload passthrough.
Explicitly excluded: build triggers, deploy triggers, parameterized job launches, any Jenkins mutation.
Console tail safety: hard caps (200 lines / 64 KiB), shared-redactor pass (redaction failure ⇒ error, never raw text), default off behind distinct jenkins.console.read operation.
Credentials/profile: jenkins-mcp boundary per ADR-0001; token by reference (JENKINS_TOKEN_SOURCE_NAME); namespaced allowed_operations; fail closed on missing config; Jenkins credentials never enter the Gitea MCP runtime.
Failure behavior: unknown job (explicit not-found, never fuzzy-guess), unreachable/timeout, 502/503/504, 401/403, malformed JSON — all safe + redacted.
Job mapping: deferred to #77 with fixed constraints (no silent guessing; multibranch encoding).
Testing strategy: mocked Jenkins only; GET-only assertions, projection allowlist, no-token-in-error, cap/redaction enforcement, profile fail-closed.
Implementation-readiness checklist gating on ADR-0001 owner decision #1, #76 profile schema, #77 mapping.

Checks

py_compile mcp_server.py / manage_labels.py / gitea_auth.py — OK
bash -n scripts/clear-provenance — OK
git diff --check — clean
pytest tests/ -q — 345 passed
Secret sweep (staged diff; no repo scanner) — clean

Scope

One new Markdown file. Untouched: #86 (other LLM), #65/#66, PR #64/#63 release work, all code.

🤖 Generated with Claude Code

Implements #72. Design documentation only — **no implementation**, no code changes, no Jenkins code in `mcp_server.py`. Adds `docs/architecture/jenkins-readonly-build-status-design.md` (alongside ADR-0001). ## What it covers (per #72 acceptance criteria) - **Minimum read-only tool set:** `jenkins_whoami`, `jenkins_list_jobs`, `jenkins_latest_build`, `jenkins_build_status`, `jenkins_get_build`, optional approval-gated `jenkins_console_tail`. All `GET`-only. - **Latest build status** + safe field allowlist: build URL, number, branch, timestamp, duration, result (`null`+building → `IN_PROGRESS`), best-effort commit SHA. No raw payload passthrough. - **Explicitly excluded:** build triggers, deploy triggers, parameterized job launches, any Jenkins mutation. - **Console tail safety:** hard caps (200 lines / 64 KiB), shared-redactor pass (redaction failure ⇒ error, never raw text), default off behind distinct `jenkins.console.read` operation. - **Credentials/profile:** `jenkins-mcp` boundary per ADR-0001; token by reference (`JENKINS_TOKEN_SOURCE_NAME`); namespaced `allowed_operations`; fail closed on missing config; **Jenkins credentials never enter the Gitea MCP runtime**. - **Failure behavior:** unknown job (explicit not-found, never fuzzy-guess), unreachable/timeout, 502/503/504, 401/403, malformed JSON — all safe + redacted. - **Job mapping:** deferred to #77 with fixed constraints (no silent guessing; multibranch encoding). - **Testing strategy:** mocked Jenkins only; GET-only assertions, projection allowlist, no-token-in-error, cap/redaction enforcement, profile fail-closed. - **Implementation-readiness checklist** gating on ADR-0001 owner decision #1, #76 profile schema, #77 mapping. ## Checks - `py_compile mcp_server.py` / `manage_labels.py` / `gitea_auth.py` — OK - `bash -n scripts/clear-provenance` — OK - `git diff --check` — clean - `pytest tests/ -q` — 345 passed - Secret sweep (staged diff; no repo scanner) — clean ## Scope One new Markdown file. Untouched: #86 (other LLM), #65/#66, PR #64/#63 release work, all code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jcwalker3 added 1 commit 2026-07-02 13:34:40 -05:00

docs: Jenkins read-only build status tools design (#72 ) 74a7e8f792

Add docs/architecture/jenkins-readonly-build-status-design.md:
implementation-ready design notes for the jenkins-mcp read-only tool set —
minimum tools (whoami, list_jobs, latest_build, build_status, get_build,
gated console_tail), safe return-field allowlist (url, number, timestamp,
duration, branch, result, commit), fail-closed failure behavior (unknown
job, unreachable, 5xx, auth, malformed JSON), bounded+redacted console tail
behind a distinct jenkins.console.read operation, per-service credential/
profile requirements (token by reference, fail closed), explicit exclusions
(build/deploy triggers, parameterized launches), job addressing with mapping
deferred to #77, and a mocked-Jenkins testing strategy.

Design only; no implementation, no code behavior changed, no Jenkins code
in mcp_server.py.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sysadmin reviewed 2026-07-02 14:01:22 -05:00

sysadmin left a comment

Reviewed PR #88. Checks passed: py_compile for mcp_server.py/manage_labels.py/gitea_auth.py, bash -n scripts/clear-provenance, full pytest suite, and git diff --check. Manual review confirms this is documentation/design only, read-only Phase 1 only, no Jenkins implementation code, credentials remain isolated from Gitea MCP, console tail behavior is bounded/redacted, mapping is deferred to #77, and triggers/deploys/rebuilds/parameterized launches are excluded.