docs: Jenkins repo/branch/PR to job mapping design (#77) #91

2026-07-02T14:10:15-05:00

jcwalker3 commented

2026-07-02 14:10:15 -05:00

Implements #77. Design documentation only — no implementation, no code changes, no Jenkins write actions.

Adds docs/architecture/jenkins-job-mapping-design.md, the mapping layer that #72's read-only tools design (merged, PR #88) explicitly deferred here.

What it covers (per #77 acceptance criteria)

Mapping format: declarative, versioned config; exact-match repo / optional branch entries → foldered Jenkins job path + type (multibranch / single / parameterized-view). No globs in v1. Malformed/duplicate entries ⇒ config load fails closed naming the entry.
Branch/ref/fork/PR precedence: branch-pinned entry > repo-wide entry > explicit no-mapping. PRs resolve via base repo only (forks never consulted). Multibranch addressing: URL-encoded branch (feature%2Fx), PR-<n>.
Explicit no-match behavior: machine-checkable {"mapped": false, ...} payload; never guesses, constructs, probes, or fuzzy-matches job names.
Config location: lives in the jenkins-mcp package (shared team fact, no secrets, committable), env-overridable path for tests; reload at server start.
Tool surface: read-only jenkins_resolve_job (pure config lookup, zero Jenkins API calls); status tools accept job-path or (repo, branch) via the same layer.
Testing strategy: mocked config + mocked Jenkins API — precedence, encoding, fork semantics, fail-closed loads, no-network-on-no-match, no-secret assertions.
Standalone justification (per the curated issue's condition) + readiness gating on ADR-0001 owner decision #1 / #76 profile schema.

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 — 355 passed
Secret sweep (staged diff; no repo scanner) — clean

Scope

One new Markdown file. Untouched: PR #89/#79 (other LLM), #80 branch (other LLM), #64/#63 release, #65/#66, all code.

🤖 Generated with Claude Code

Implements #77. Design documentation only — **no implementation**, no code changes, no Jenkins write actions. Adds `docs/architecture/jenkins-job-mapping-design.md`, the mapping layer that #72's read-only tools design (merged, PR #88) explicitly deferred here. ## What it covers (per #77 acceptance criteria) - **Mapping format:** declarative, versioned config; exact-match `repo` / optional `branch` entries → foldered Jenkins `job` path + `type` (`multibranch` / `single` / `parameterized-view`). No globs in v1. Malformed/duplicate entries ⇒ config load **fails closed** naming the entry. - **Branch/ref/fork/PR precedence:** branch-pinned entry > repo-wide entry > explicit no-mapping. PRs resolve via **base repo only** (forks never consulted). Multibranch addressing: URL-encoded branch (`feature%2Fx`), `PR-<n>`. - **Explicit no-match behavior:** machine-checkable `{"mapped": false, ...}` payload; **never** guesses, constructs, probes, or fuzzy-matches job names. - **Config location:** lives in the `jenkins-mcp` package (shared team fact, no secrets, committable), env-overridable path for tests; reload at server start. - **Tool surface:** read-only `jenkins_resolve_job` (pure config lookup, zero Jenkins API calls); status tools accept job-path or `(repo, branch)` via the same layer. - **Testing strategy:** mocked config + mocked Jenkins API — precedence, encoding, fork semantics, fail-closed loads, no-network-on-no-match, no-secret assertions. - **Standalone justification** (per the curated issue's condition) + readiness gating on ADR-0001 owner decision #1 / #76 profile schema. ## 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` — 355 passed - Secret sweep (staged diff; no repo scanner) — clean ## Scope One new Markdown file. Untouched: PR #89/#79 (other LLM), #80 branch (other LLM), #64/#63 release, #65/#66, all code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jcwalker3 added 1 commit 2026-07-02 14:10:15 -05:00

docs: Jenkins repo/branch/PR to job mapping design (#77 ) 1bc2f20623

Add docs/architecture/jenkins-job-mapping-design.md: declarative versioned
mapping config (exact-match repo/branch entries, no globs, fail-closed load
on malformed/duplicate entries), resolution semantics for multibranch/
single/parameterized-view job types with URL-encoded branch and PR-<n>
addressing, branch-pinned-over-repo-wide precedence, fork PRs resolving via
base repo only, explicit machine-checkable no-match payload (never guess or
probe job names), config location in the jenkins-mcp package (no secrets,
env-overridable path), a read-only jenkins_resolve_job tool surface, and a
mocked-config/mocked-Jenkins testing strategy.

Design only; no implementation, no code behavior changed, no Jenkins write
actions introduced.

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

sysadmin reviewed 2026-07-02 14:15:40 -05:00

sysadmin left a comment

Approve. Reviewed head 1bc2f20 from a detached review worktree.

Scope: exactly one new file, docs/architecture/jenkins-job-mapping-design.md (+165). Design documentation only — no code, no Jenkins write actions, no unrelated files. Based on current master (007b5da), zero commits behind.

Acceptance criteria (#77) — all met:

Mapping format defined (§2): declarative versioned config, exact-match repo/branch, foldered job paths, three types; malformed/duplicate entries fail closed at load. ✓
Branch/ref/fork/PR precedence (§4): branch-pinned > repo-wide > explicit no-mapping; PRs resolve via base repo only, forks never consulted. ✓
Foldered Jenkins jobs supported (/-joined paths, URL-encoded branch addressing). ✓
Explicit no-match behavior (§5): machine-checkable {"mapped": false}; never constructs, probes, or fuzzy-matches job names. ✓
Config location documented (§6): jenkins-mcp package, env-overridable for tests, no secrets. ✓
Testing strategy with mocked Jenkins API (§8), including no-network-on-no-match and no-secret assertions. ✓
No Jenkins write actions anywhere; readiness gated on ADR-0001 decision #1 / #76. ✓
Standalone-worthiness condition from the curated issue addressed explicitly (§9). ✓

Sibling link target jenkins-readonly-build-status-design.md exists (merged via #88). Consistent with the #72 design and trust-boundary model.

Checks (review worktree at 1bc2f20): py_compile mcp_server/manage_labels/gitea_auth OK · bash -n scripts/clear-provenance OK · pytest tests/ -q 355 passed · git diff --check clean · staged-diff secret sweep clean. Gitea reports mergeable.

Review Metadata:

LLM-Agent-SHA: llm-a38fff25edeb
LLM-Role: reviewer
Authenticated-Gitea-User: sysadmin
MCP-Profile: prgs-reviewer
Eligibility: passed (PR author jcwalker3 ≠ reviewer sysadmin)

Approve. Reviewed head `1bc2f20` from a detached review worktree. Scope: exactly one new file, `docs/architecture/jenkins-job-mapping-design.md` (+165). Design documentation only — no code, no Jenkins write actions, no unrelated files. Based on current master (`007b5da`), zero commits behind. Acceptance criteria (#77) — all met: - Mapping format defined (§2): declarative versioned config, exact-match `repo`/`branch`, foldered `job` paths, three `type`s; malformed/duplicate entries fail closed at load. ✓ - Branch/ref/fork/PR precedence (§4): branch-pinned > repo-wide > explicit no-mapping; PRs resolve via base repo only, forks never consulted. ✓ - Foldered Jenkins jobs supported (`/`-joined paths, URL-encoded branch addressing). ✓ - Explicit no-match behavior (§5): machine-checkable `{"mapped": false}`; never constructs, probes, or fuzzy-matches job names. ✓ - Config location documented (§6): jenkins-mcp package, env-overridable for tests, no secrets. ✓ - Testing strategy with mocked Jenkins API (§8), including no-network-on-no-match and no-secret assertions. ✓ - No Jenkins write actions anywhere; readiness gated on ADR-0001 decision #1 / #76. ✓ - Standalone-worthiness condition from the curated issue addressed explicitly (§9). ✓ Sibling link target `jenkins-readonly-build-status-design.md` exists (merged via #88). Consistent with the #72 design and trust-boundary model. Checks (review worktree at 1bc2f20): py_compile mcp_server/manage_labels/gitea_auth OK · `bash -n scripts/clear-provenance` OK · `pytest tests/ -q` **355 passed** · `git diff --check` clean · staged-diff secret sweep clean. Gitea reports mergeable. Review Metadata: - LLM-Agent-SHA: llm-a38fff25edeb - LLM-Role: reviewer - Authenticated-Gitea-User: sysadmin - MCP-Profile: prgs-reviewer - Eligibility: passed (PR author jcwalker3 ≠ reviewer sysadmin)

sysadmin merged commit 4f5b732741 into master

2026-07-02 14:15:59 -05:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#91