Gitea Client

Package: forge.lthn.ai/core/go-scm/gitea
Wraps: code.gitea.io/sdk/gitea

Thin wrapper around the Gitea Go SDK providing config-based authentication, paginated listing helpers, and convenience methods for managing repositories, issues, pull requests, and mirrors on a Gitea instance. Mirrors the Forge-Client pattern for Gitea instances such as git.lthn.ai.

Authentication

Credentials are resolved from three sources, each overriding the previous:

Config file -- ~/.core/config.yaml keys gitea.token and gitea.url
Environment variables -- GITEA_TOKEN and GITEA_URL
Flag overrides -- passed directly to NewFromConfig(flagURL, flagToken)

If no URL is configured, it defaults to https://gitea.snider.dev.

// Explicit credentials
client, err := gitea.New("https://git.lthn.ai", "my-token")

// Auto-resolve from config/env/flags
client, err := gitea.NewFromConfig("", "")

// Resolve without creating a client
url, token, err := gitea.ResolveConfig("", "")

Persisting Configuration

err := gitea.SaveConfig("https://git.lthn.ai", "my-token")

Client Methods

Core

Method	Signature	Description
`API()`	`*gitea.Client`	Expose the underlying SDK client for direct access
`URL()`	`string`	Return the Gitea instance URL

Repositories

Method	Signature	Description
`GetRepo(owner, name)`	`(*gitea.Repository, error)`	Get a single repository
`ListOrgRepos(org)`	`([]*gitea.Repository, error)`	List all repos in an organisation (paginated)
`ListUserRepos()`	`([]*gitea.Repository, error)`	List all repos for the authenticated user (paginated)
`CreateOrgRepo(org, opts)`	`(*gitea.Repository, error)`	Create a new repo under an organisation
`CreateMirror(owner, name, cloneURL, authToken)`	`(*gitea.Repository, error)`	Create a pull mirror from a GitHub clone URL
`DeleteRepo(owner, name)`	`error`	Delete a repository

Issues

Method	Signature	Description
`ListIssues(owner, repo, opts)`	`([]*gitea.Issue, error)`	List issues with state/pagination filters
`GetIssue(owner, repo, number)`	`(*gitea.Issue, error)`	Get a single issue
`CreateIssue(owner, repo, opts)`	`(*gitea.Issue, error)`	Create a new issue

ListIssuesOpts

type ListIssuesOpts struct {
    State string // "open", "closed", "all" (default: "open")
    Page  int    // Page number (default: 1)
    Limit int    // Items per page (default: 50)
}

Pull Requests

Method	Signature	Description
`ListPullRequests(owner, repo, state)`	`([]*gitea.PullRequest, error)`	List PRs by state (paginated)
`GetPullRequest(owner, repo, number)`	`(*gitea.PullRequest, error)`	Get a single PR

PR Metadata (Pipeline Support)

The PRMeta struct mirrors the Forge-Client PRMeta and extracts structural signals for AI-driven pipelines:

type PRMeta struct {
    Number       int64
    Title        string
    State        string
    Author       string
    Branch       string
    BaseBranch   string
    Labels       []string
    Assignees    []string
    IsMerged     bool
    CreatedAt    time.Time
    UpdatedAt    time.Time
    CommentCount int
}

Method	Signature	Description
`GetPRMeta(owner, repo, pr)`	`(*PRMeta, error)`	Get structural signals for a PR
`GetCommentBodies(owner, repo, pr)`	`([]Comment, error)`	Get all comment bodies with metadata
`GetIssueBody(owner, repo, issue)`	`(string, error)`	Get the body text of an issue

Mirroring Repositories

The Gitea client includes a CreateMirror method for setting up pull mirrors from GitHub. This is used to maintain reduced-data mirrors on git.lthn.ai:

client, err := gitea.New("https://git.lthn.ai", token)

// Create a public mirror (no auth needed for public repos)
repo, err := client.CreateMirror("Agentic", "core-go", "https://github.com/host-uk/core.git", "")

// Create a mirror of a private repo (pass GitHub PAT)
repo, err := client.CreateMirror("Agentic", "private-repo", "https://github.com/host-uk/private.git", githubToken)

Differences from Forge Client

The Gitea client is deliberately smaller than the Forge-Client because git.lthn.ai serves as a public mirror with reduced data. Key differences:

Feature	Forge Client	Gitea Client
Labels	Full CRUD + EnsureLabel	Not implemented
Webhooks	Create + List	Not implemented
Organisations	List + Get + Create	Not implemented
PR merge/draft	MergePullRequest, SetPRDraft	Not implemented
PR reviews	ListPRReviews, DismissReview	Not implemented
Mirroring	MigrateRepo (generic)	CreateMirror (GitHub-specific)
Default URL	`http://localhost:4000`	`https://gitea.snider.dev`

Both clients share the same authentication resolution pattern, the same PRMeta/Comment types, and the same log.E() error handling convention.