forgejo-sdk

Python SDK wrapping the Forgejo REST API via httpx.

API Reference

swagger.v1.json is the full OpenAPI spec from the live Forgejo instance (v14.0.2, 304 endpoints). Use it as the source of truth for endpoint paths, parameters, and response shapes.

Priority Endpoints

The SDK should cover these first (what agents actually use):

Issues

• POST /api/v1/repos/{owner}/{repo}/issues — create issue
• GET /api/v1/repos/{owner}/{repo}/issues/{index} — get issue
• GET /api/v1/repos/{owner}/{repo}/issues — list issues
• POST /api/v1/repos/{owner}/{repo}/issues/{index}/comments — comment (works for PRs too)

Pull Requests

• POST /api/v1/repos/{owner}/{repo}/pulls — create PR
• GET /api/v1/repos/{owner}/{repo}/pulls — list PRs
• GET /api/v1/repos/{owner}/{repo}/pulls/{index} — get PR details
• POST /api/v1/repos/{owner}/{repo}/pulls/{index}/merge — merge PR (body: {"Do":"squash"})
• GET /api/v1/repos/{owner}/{repo}/pulls/{index}.diff — get PR diff (also available at web URL without auth)

Repos

• GET /api/v1/repos/{owner}/{repo} — get repo
• GET /api/v1/user/repos — list user's repos
• GET /api/v1/repos/{owner}/{repo}/branches — list branches

Auth

HTTP Basic Auth: ForgejoClient(base_url, username, password).

Pattern

Same as ldraney/notion-sdk — pure httpx wrapper, no MCP dependency. The MCP layer (ldraney/forgejo-mcp) wraps this SDK.