Gitea-Tools/docs/architecture/jenkins-readonly-build-status-design.md

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