docs: 📝 openspec change — branch protection management (branch-protection capability) #195

Merged

goern merged 0 commits from refs/pull/195/head into main 2026-06-02 14:15:15 +00:00

Conversation 6 Commits - Files changed -

goern commented 2026-06-02 14:11:11 +00:00 (Migrated from codeberg.org)

Copy link

What

OpenSpec proposal for forgejo-mcp-uc6: a new branch-protection capability. Spec-only — no code in this PR (implementation follows in a separate PR, matching the label-crud lifecycle).

Why

forgejo-mcp-f6h: a repo with no branch protection let Renovate automerge a PR while its required commit status was still pending. The server has no MCP surface for Forgejo branch protection — operators can't see or fix the misconfig. This capability adds read + enforcement.

Proposed surface

• Tools (5): list_branch_protections, get_branch_protection, create_branch_protection, edit_branch_protection, delete_branch_protection — over /repos/{owner}/{repo}/branch_protections (SDK already binds these).
• Resources (2): bounded collection forgejo://repo/{owner}/{repo}/branch_protections + single forgejo://repo/{owner}/{repo}/branch_protection/{rule}.

Key design decisions (see design.md)

• Self-contained capability — no delta against mcp-resources-core (still owned by the unarchived mcp-resource-templates change); bounding (output-bounding.md) + the forgejo:// URI scheme are cited as constraints. Avoids a cross-change archive-ordering hazard.
• New operation/branchprotection/ package; ParseBranchProtection(s) added to operation/resource.
• List tool + collection resource satisfy output-bounding (page/limit, resumable, EmbeddedListCap sentinel naming list_branch_protections).
• edit uses PATCH pointer semantics (only caller-passed fields change); create/edit round-trip status_check_contexts.
• Focused param subset (the f6h fields + common hardening), not all ~22 rule fields.

Artifacts

proposal.md · design.md · specs/branch-protection/spec.md (7 requirements, each with scenarios) · tasks.md (6 task groups).

openspec validate branch-protection-management --strict   # → valid

After merge

Implement against the tasks (full CRUD + both resources + httptest coverage) in a follow-up PR, then archive. A partial implementation (URI parsers + param descriptions) is already stashed locally to seed that PR.

---

Part of forgejo-mcp-uc6. Discovered from forgejo-mcp-f6h.

## What OpenSpec **proposal** for `forgejo-mcp-uc6`: a new `branch-protection` capability. **Spec-only** — no code in this PR (implementation follows in a separate PR, matching the label-crud lifecycle). ## Why `forgejo-mcp-f6h`: a repo with no branch protection let Renovate automerge a PR while its required commit status was still `pending`. The server has no MCP surface for Forgejo branch protection — operators can't see or fix the misconfig. This capability adds read + enforcement. ## Proposed surface - **Tools (5)**: `list_branch_protections`, `get_branch_protection`, `create_branch_protection`, `edit_branch_protection`, `delete_branch_protection` — over `/repos/{owner}/{repo}/branch_protections` (SDK already binds these). - **Resources (2)**: bounded collection `forgejo://repo/{owner}/{repo}/branch_protections` + single `forgejo://repo/{owner}/{repo}/branch_protection/{rule}`. ## Key design decisions (see `design.md`) - **Self-contained capability** — no delta against `mcp-resources-core` (still owned by the unarchived `mcp-resource-templates` change); bounding (`output-bounding.md`) + the `forgejo://` URI scheme are cited as constraints. Avoids a cross-change archive-ordering hazard. - New `operation/branchprotection/` package; `ParseBranchProtection(s)` added to `operation/resource`. - List tool + collection resource satisfy output-bounding (`page`/`limit`, resumable, `EmbeddedListCap` sentinel naming `list_branch_protections`). - `edit` uses PATCH pointer semantics (only caller-passed fields change); `create`/`edit` round-trip `status_check_contexts`. - Focused param subset (the `f6h` fields + common hardening), not all ~22 rule fields. ## Artifacts `proposal.md` · `design.md` · `specs/branch-protection/spec.md` (7 requirements, each with scenarios) · `tasks.md` (6 task groups). ``` openspec validate branch-protection-management --strict # → valid ``` ## After merge Implement against the tasks (full CRUD + both resources + httptest coverage) in a follow-up PR, then archive. A partial implementation (URI parsers + param descriptions) is already stashed locally to seed that PR. --- Part of forgejo-mcp-uc6. Discovered from forgejo-mcp-f6h.

op1st-gitops commented 2026-06-02 14:11:33 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-openspec-validate-pr-4lrcx is running.

Starting Pipelinerun forgejo-mcp-openspec-validate-pr-4lrcx in namespace op1st-pipelines

You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:

tkn pr logs -n op1st-pipelines forgejo-mcp-openspec-validate-pr-4lrcx -f

op1st Pipelines as Code/forgejo-mcp-openspec-validate-pr-4lrcx is running. Starting Pipelinerun <b>[forgejo-mcp-openspec-validate-pr-4lrcx](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-openspec-validate-pr-4lrcx)</b> in namespace <b>op1st-pipelines</b> You can monitor the execution using the [op1st Pipelines as Code](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-openspec-validate-pr-4lrcx) PipelineRun viewer or through the command line by using the [tkn](https://tekton.dev/docs/cli/#installation) CLI with the following command: <code>tkn pr logs -n op1st-pipelines forgejo-mcp-openspec-validate-pr-4lrcx -f</code>

op1st-gitops commented 2026-06-02 14:11:33 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-on-pull-request-b46cz is running.

Starting Pipelinerun forgejo-mcp-on-pull-request-b46cz in namespace op1st-pipelines

You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:

tkn pr logs -n op1st-pipelines forgejo-mcp-on-pull-request-b46cz -f

op1st Pipelines as Code/forgejo-mcp-on-pull-request-b46cz is running. Starting Pipelinerun <b>[forgejo-mcp-on-pull-request-b46cz](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz)</b> in namespace <b>op1st-pipelines</b> You can monitor the execution using the [op1st Pipelines as Code](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz) PipelineRun viewer or through the command line by using the [tkn](https://tekton.dev/docs/cli/#installation) CLI with the following command: <code>tkn pr logs -n op1st-pipelines forgejo-mcp-on-pull-request-b46cz -f</code>

op1st-gitops commented 2026-06-02 14:11:33 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-code-scans-qltz7 is running.

Starting Pipelinerun forgejo-mcp-code-scans-qltz7 in namespace op1st-pipelines

You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:

tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-qltz7 -f

op1st Pipelines as Code/forgejo-mcp-code-scans-qltz7 is running. Starting Pipelinerun <b>[forgejo-mcp-code-scans-qltz7](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7)</b> in namespace <b>op1st-pipelines</b> You can monitor the execution using the [op1st Pipelines as Code](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7) PipelineRun viewer or through the command line by using the [tkn](https://tekton.dev/docs/cli/#installation) CLI with the following command: <code>tkn pr logs -n op1st-pipelines forgejo-mcp-code-scans-qltz7 -f</code>

op1st-gitops commented 2026-06-02 14:12:01 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-openspec-validate-pr-4lrcx has successfully validated your commit.

• Namespace: op1st-pipelines
• PipelineRun: forgejo-mcp-openspec-validate-pr-4lrcx

---

Task Statuses:

Status	Duration	Name
Succeeded	13 seconds	fetch-source
Succeeded	14 seconds	validate

op1st Pipelines as Code/forgejo-mcp-openspec-validate-pr-4lrcx has <b>successfully</b> validated your commit. <ul> <li><b>Namespace</b>: <a href="https://detailurl.setting.custom-console-url-namespace.is.not.configured">op1st-pipelines</a></li> <li><b>PipelineRun:</b> <a href="https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-openspec-validate-pr-4lrcx">forgejo-mcp-openspec-validate-pr-4lrcx</a></li> </ul> <hr> <h4>Task Statuses:</h4> <table> <tr><th>Status</th><th>Duration</th><th>Name</th></tr> <tr> <td>Succeeded</td> <td>13 seconds</td><td> [fetch-source](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-openspec-validate-pr-4lrcx/logs/fetch-source) </td></tr> <tr> <td>Succeeded</td> <td>14 seconds</td><td> [validate](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-openspec-validate-pr-4lrcx/logs/validate) </td></tr> </table>

op1st-gitops commented 2026-06-02 14:12:06 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-code-scans-qltz7 has successfully validated your commit.

• Namespace: op1st-pipelines
• PipelineRun: forgejo-mcp-code-scans-qltz7

---

Task Statuses:

Status	Duration	Name
Succeeded	13 seconds	fetch-source
Succeeded	9 seconds	gitleaks-version
Succeeded	11 seconds	gitleaks

op1st Pipelines as Code/forgejo-mcp-code-scans-qltz7 has <b>successfully</b> validated your commit. <ul> <li><b>Namespace</b>: <a href="https://detailurl.setting.custom-console-url-namespace.is.not.configured">op1st-pipelines</a></li> <li><b>PipelineRun:</b> <a href="https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7">forgejo-mcp-code-scans-qltz7</a></li> </ul> <hr> <h4>Task Statuses:</h4> <table> <tr><th>Status</th><th>Duration</th><th>Name</th></tr> <tr> <td>Succeeded</td> <td>13 seconds</td><td> [fetch-source](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7/logs/fetch-source) </td></tr> <tr> <td>Succeeded</td> <td>9 seconds</td><td> [gitleaks-version](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7/logs/gitleaks-version) </td></tr> <tr> <td>Succeeded</td> <td>11 seconds</td><td> [gitleaks](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-code-scans-qltz7/logs/gitleaks) </td></tr> </table>

op1st-gitops commented 2026-06-02 14:13:59 +00:00 (Migrated from codeberg.org)

Copy link

op1st Pipelines as Code/forgejo-mcp-on-pull-request-b46cz has successfully validated your commit.

• Namespace: op1st-pipelines
• PipelineRun: forgejo-mcp-on-pull-request-b46cz

---

Task Statuses:

Status	Duration	Name
Succeeded	12 seconds	fetch-source
Succeeded	2 minutes	build-and-test
Succeeded	16 seconds	commit-title-check

op1st Pipelines as Code/forgejo-mcp-on-pull-request-b46cz has <b>successfully</b> validated your commit. <ul> <li><b>Namespace</b>: <a href="https://detailurl.setting.custom-console-url-namespace.is.not.configured">op1st-pipelines</a></li> <li><b>PipelineRun:</b> <a href="https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz">forgejo-mcp-on-pull-request-b46cz</a></li> </ul> <hr> <h4>Task Statuses:</h4> <table> <tr><th>Status</th><th>Duration</th><th>Name</th></tr> <tr> <td>Succeeded</td> <td>12 seconds</td><td> [fetch-source](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz/logs/fetch-source) </td></tr> <tr> <td>Succeeded</td> <td>2 minutes</td><td> [build-and-test](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz/logs/build-and-test) </td></tr> <tr> <td>Succeeded</td> <td>16 seconds</td><td> [commit-title-check](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/forgejo-mcp-on-pull-request-b46cz/logs/commit-title-check) </td></tr> </table>

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

Compat/Breaking

Breaking change that won't be backward compatible

  

Kind/Bug

Something is not working

  

Kind/Documentation

Documentation changes

  

Kind/Enhancement

Improve existing functionality

  

Kind/Feature

New functionality

  

Kind/OpenSpec

OpenSpec change proposal / spec-driven work

  

Kind/Security

This is security issue

  

Kind/Testing

Issue or pull request related to testing

  

Priority/Critical

The priority is critical

  

Priority/High

The priority is high

  

Priority/Low

The priority is low

  

Priority/Medium

The priority is medium

  

RFC - Request For Comments

Request For Comments — design/spec open for feedback before implementation

  

Reviewed/Confirmed

Issue has been confirmed

  

Reviewed/Duplicate

This issue or pull request already exists

  

Reviewed/Invalid

Invalid issue

  

Reviewed/Won't Fix

This issue won't be fixed

  

Status/Abandoned

Somebody has started to work on this but abandoned work

  

Status/Blocked

Something is blocking this issue or pull request

  

Status/Need More Info

Feedback is required to reproduce issue or to continue work

  

hermes-attempted

Hermes attempted but produced no changes

  

hermes-needs-clarification

Quality gate flagged, needs human input

  

hermes-ready

Ready for hermes to process

  

hermes-review

Hermes PR awaiting review

  

hermes-wip

Hermes is working on this

  

human-required

Hermes gave up after 3 attempts

No labels

Compat/Breaking

Kind/Bug

Kind/Documentation

Kind/Enhancement

Kind/Feature

Kind/OpenSpec

Kind/Security

Kind/Testing

Priority/Critical

Priority/High

Priority/Low

Priority/Medium

RFC - Request For Comments

Reviewed/Confirmed

Reviewed/Duplicate

Reviewed/Invalid

Reviewed/Won't Fix

Status/Abandoned

Status/Blocked

Status/Need More Info

hermes-attempted

hermes-needs-clarification

hermes-ready

hermes-review

hermes-wip

human-required

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

agentic-forges/forgejo-mcp!195

No description provided.