gitea-mcp/docs/superpowers/specs/2026-05-06-gitops-agent-tools-design.md

GitOps Agent Tools — Design Spec

Date: 2026-05-06 Status: Approved

Goal

Extend the Gitea MCP server with the tools an AI agent needs to drive a full GitOps development loop autonomously — reading repo state, deciding on a branching strategy, making changes, opening and merging PRs, and tagging releases — without any local git tooling.

The agent selects between feature-branch and trunk-based development based on branch protection rules it reads at runtime.

---

New Tools (9)

All tools follow the existing pattern: one file in internal/tools/, one Gitea client method in internal/gitea/, allowlist check on owner, table-driven tests in both packages.

repo_status

Convenience read tool — returns branch list, open PRs, and protection info for a target branch in a single call. Designed for the agent's first query on any repo so it can decide its strategy.

Inputs: owner, name, branch (optional — defaults to repo default branch) Output: { branches: [...], open_prs: [...], protection: { protected, required_approvals, push_whitelist, merge_whitelist } } Implementation: calls ListBranches + ListPullRequests(state=open) + GetBranchProtection internally, composes result. No new Gitea API surface.

---

branch_list

Inputs: owner, name, page (optional), limit (optional, default 30) Output: array of { name, sha } Gitea endpoint: GET /api/v1/repos/{owner}/{repo}/branches

---

branch_delete

Inputs: owner, name, branch Output: confirmation message Gitea endpoint: DELETE /api/v1/repos/{owner}/{repo}/branches/{branch} Error handling: 403 from Gitea (protected branch) surfaced as a descriptive error.

---

branch_protection_get

Inputs: owner, name, branch Output: { protected, required_approvals, push_whitelist, merge_whitelist } Gitea endpoint: GET /api/v1/repos/{owner}/{repo}/branch_protections/{branch} Error handling: 404 → return { protected: false }, not an error. Allows agent to make clean boolean decisions.

---

pr_list

Inputs: owner, name, state (open/closed/all, default open), head (optional branch filter), page, limit Output: array of { number, title, state, head_branch, base_branch, draft, html_url } Gitea endpoint: GET /api/v1/repos/{owner}/{repo}/pulls

---

pr_merge

Inputs: owner, name, index, style (merge/squash/rebase, default merge), merge_message_title (optional), merge_message_field (optional) Output: { merged: true, commit_sha } — if Gitea returns 204 No Content (some merge styles), output is { merged: true } without commit_sha. Gitea endpoint: POST /api/v1/repos/{owner}/{repo}/pulls/{index}/merge Error handling: 405 (checks failing) and 409 (merge conflict) passed through with the Gitea error message intact so the agent understands why it failed.

---

dir_list

Inputs: owner, name, path (empty string = repo root), ref (optional branch/tag/SHA) Output: array of { name, path, type (file|dir|symlink), sha, size } Gitea endpoint: GET /api/v1/repos/{owner}/{repo}/contents/{path} Note: same endpoint as file_read but returns an array when path is a directory. Client detects response shape (array vs object). If called on a file path, returns a descriptive error: "path is a file, not a directory — use file_read".

---

file_delete

Inputs: owner, name, path, branch, message, sha (required — current blob SHA) Output: { commit_sha, html_url } Gitea endpoint: DELETE /api/v1/repos/{owner}/{repo}/contents/{path}

---

tag_create

Inputs: owner, name, tag (tag name), target (branch name or commit SHA), message (optional — creates annotated tag if set) Output: { tag, commit_sha, html_url } Gitea endpoint: POST /api/v1/repos/{owner}/{repo}/tags

---

Gitea Client Methods

New methods on gitea.Client:

Method	Endpoint	HTTP verb
ListBranches(ctx, owner, repo, page, limit)	/api/v1/repos/{owner}/{repo}/branches	GET
DeleteBranch(ctx, owner, repo, branch)	/api/v1/repos/{owner}/{repo}/branches/{branch}	DELETE
GetBranchProtection(ctx, owner, repo, branch)	/api/v1/repos/{owner}/{repo}/branch_protections/{branch}	GET
ListPullRequests(ctx, owner, repo, state, head, page, limit)	/api/v1/repos/{owner}/{repo}/pulls	GET
MergePullRequest(ctx, owner, repo, index, args)	/api/v1/repos/{owner}/{repo}/pulls/{index}/merge	POST
ListContents(ctx, owner, repo, path, ref)	/api/v1/repos/{owner}/{repo}/contents/{path}	GET
DeleteFile(ctx, owner, repo, path, args)	/api/v1/repos/{owner}/{repo}/contents/{path}	DELETE
CreateTag(ctx, owner, repo, args)	/api/v1/repos/{owner}/{repo}/tags	POST

---

Architecture

No structural changes. Each new tool is:

• One file: internal/tools/<tool_name>.go + internal/tools/<tool_name>_test.go
• One client method: internal/gitea/<domain>.go (added to existing domain files where logical)
• Registered in cmd/gitea-mcp/main.go

repo_status is the only tool with internal composition — it calls three client methods and merges their results. It has no dedicated client method of its own.

New client methods go in existing domain files:

• Branch methods → internal/gitea/files.go (already has BranchExists, CreateBranch)
• PR methods → internal/gitea/pulls.go
• Contents (dir_list, file_delete) → internal/gitea/files.go
• Tags → new internal/gitea/tags.go

---

Testing

Pattern: table-driven tests with a httptest.NewServer mock, same as file_write_branch_test.go.

Each tool covers:

• Happy path
• 404 response
• Allowlist rejection
• Tool-specific edge cases:
  • branch_delete: 403 protected branch
  • branch_protection_get: 404 → {protected: false} not error
  • dir_list: file path → descriptive error
  • pr_merge: 405 checks failing, 409 merge conflict
  • repo_status: any one sub-call failing propagates the error

---

Agent Decision Flow (Reference)

1. repo_status(owner, name)
   → if branch.protected && required_approvals > 0:
       use feature-branch workflow
   → else:
       use trunk-based workflow

Feature-branch workflow:
  file_write_branch (auto-creates branch)
  → pr_create
  → [wait for CI via workflow_run_status]
  → pr_merge
  → branch_delete

Trunk-based workflow:
  file_write_branch(branch=main)
  → [optionally] tag_create

Post-merge (either):
  → [optionally] tag_create to trigger deployment