Gitea backend¶
livery.forge.GiteaForge: the protocol over Gitea's REST v1 API.
Construction and the token rule¶
GiteaForge.connect() resolves the server once: an explicit url
wins, GITEA_URL is the configured default. The token defaults to
GITEA_TOKEN; a missing token raises at connect time rather than
failing later on the first write. GITEA_TOKEN belongs to the host
GITEA_URL names and no other: test a foreign host with
livery.forge.gitea_is_configured_host and read it anonymously
(token="") instead of sending it a token it never issued.
The server floor¶
The 1.28 line. Everything except run cancellation works on earlier
servers; checks.cancel_run probes the version once and raises
livery.forge.Unsupported naming it when the server predates the
cancel endpoints. Capabilities: auto_merge, force_cancel,
required_contexts, ci_secrets, min_approvals, and
schedule_events are all supported.
Mapping notes¶
- Pull requests and issues share Gitea's number space and its issue
endpoints. The backend keeps the protocol's separation: listings
pass
type=issues, andissue.geton a number that names a pull request answers None. pr.find_by_headandpr.find_by_head_sharead the listing newest first and stop at the first match. Gitea's pull request list has no head filter, so an unknownhead=is ignored and every pull request comes back.GET /repos/:owner/:repo/commits/:sha/pullfinds a pull request by its merge commit only, never by its head.pr.listreads the same listing to its end, with the state as Gitea's own filter: Gitea'sclosedholds the merged pull requests.tags(prefix)readsGET /repos/:owner/:repo/git/refs/tags/:prefix, one unpaged answer; no tag under the prefix answers 404.runswith a workflow reads that workflow's own listing, and a run'srefis itshead_branch.dispatchasks?return_run_details=true, and Gitea answers 200 naming the run inworkflow_run_id, which comes back. A server without the run's details answers 204 with no body: None comes back, and the caller finds the run inrunsby its event,refandhead_sha.pr.is_armedwalks the issue timeline, the one read-only source of the schedule; acloseormerge_pullevent clears the armed state whether or not a cancel event was emitted.issue.searchmatches text client-side over the complete listing: the protocol promises a body match and Gitea'sqfilter does not.- Labels resolve names to ids at the boundary; issue creation and
pr.add_labels(the issue labels endpoint, by id) with a label the repository does not carry are refused with the instruction to configure it first. - Releases and tags with
/in the name travel URL-encoded whole. membersandteamsspeak the org endpoints; on a personal namespace they 404, and the fallback answers the login itself and an empty team list.- The codeowners dialect is
.gitea/CODEOWNERS, the same line shape as GitHub's. Gitea has no codeowner-approval toggle:RepoConfig.require_codeowner_reviewis written asblock_on_official_review_requests, which the codeowners file feeds, andprotectionreads the answer back through the same field.
Local development¶
fm forge.dev.up starts and seeds the compose container (a 1.28
nightly with an act_runner beside it). The seed writes the credentials
to the containers' own record (.forge-dev.env) and to the shared env
file (.repo.shared.env), both in footman's config directory. The
shared file is what the env cascade reads, and it names whichever forge
is current: a local loop environment writes its own Gitea's keys
there. A test that drives the containers reads them from the record
(livery.forge.testing.rig_record_path). The conformance suite runs
three ways:
- default: replays the committed cassettes, no container, no network.
FORGE_LIVE=1: live against the container.fm forge.fixtures.record: live, rewriting the cassettes.