Skip to content

The protocol

One interface to GitHub, Gitea, and GitLab: livery.forge.Forge for one server, livery.forge.Repository for one repository on it, and livery.forge.Registry for one package index. The protocols are frozen: every backend, the verified fake included, passes the one conformance suite in livery.forge.testing, and a change to a verb now is a compatibility event.

Every verb exists because a development workflow uses it, and a verb no workflow uses is removed. There is deliberately no repository-listing verb: fleet enumeration is configuration-driven, and discovery joins the protocol only when a workflow demands it.

The rules every method obeys

  • One handle. A pull request, issue, run, or job is identified by the number or id the protocol returned for it. A backend whose server keeps two identities (GitLab's iid and global id) translates at the boundary and never leaks the other one. Pull request and issue numbers count in separate spaces: never use one as the other.
  • Listings are complete or they raise. A method that returns a sequence returns everything the query matches, or raises livery.forge.ForgeError. A truncated prefix is never returned as the answer, because "not in this list" is an answer callers act on.
  • Probe before acting. Re-running a workflow is its recovery procedure. Where a server operation is not idempotent (creating a repository, a release, a pull request), the protocol pairs it with the read that makes probe-then-act idempotent as a whole.
  • Capabilities, not pretence. Where forges differ, the difference is a named capability. forge.supports(name) answers honestly, and an operation a forge declines raises livery.forge.Unsupported naming the capability.
  • Failures carry the server's words. Every ForgeError message quotes what the server said; status, method, and endpoint attributes carry what a caller branches on. No failure is reduced to a boolean.

Capabilities

Name Meaning GitHub Gitea (1.28 floor) GitLab
auto_merge a merge can be scheduled to fire when checks go green yes yes yes (merge when pipeline succeeds)
force_cancel a run whose runner stopped answering can be cancelled immediately yes yes no
required_contexts branch protection names the check contexts that must pass yes yes no
ci_secrets RepoConfig.secrets can be stored through the backend with the github-secrets extra (sealed-box encryption via PyNaCl); a bare install declines by name yes yes (masked variables)
min_approvals protection can require approving reviews (and a codeowner's) before merge yes yes per instance: GitLab licence-gates approval rules, and supports probes the licence once per connection
schedule_events the merge-scheduling history of a pull request can be read yes yes yes (reconstructed from system notes and state events)

The verbs

Forge: one server

Verb Does
whoami() the token's login name; the first probe of anything unattended
server_version() the server's version; backends with a floor raise Unsupported naming it
supports(capability) the honesty valve
repository(owner, name) the Repository view; cheap, no network
create_repo(owner, name, *, private, description) create, initialised with an unprotected default branch the creator may push over; raises when it exists
get_repo(owner, name) settings or None; the probe that makes creation re-runnable
delete_repo(owner, name) idempotent
user_url(login) the profile address; string building, nothing on the wire
members(owner) the org's member logins; a user namespace answers its one login (the endpoints 404 there)
teams(owner) the org's team names; a user namespace answers empty
codeowners(entries) renders the forge's CODEOWNERS dialect from neutral entries; pure string building, offline

Repository: repository-level

Verb Does
configure(config) idempotent drift repair; None fields untouched; see livery.forge.RepoConfig
tags(prefix="") every tag name, or those starting with prefix, matched by the forge; the release train's existence probe
branch_exists(branch) existence
protection(branch) the branch's livery.forge.Protection, or None; what a backend cannot read reads as inert
delete_branch(branch) idempotent; the abort path's cleanup (merge-path deletion is configuration)
web_url() the repository's home page
pr_url(number) the pull request's address
issue_url(number) the issue's address
commit_url(sha) the commit's address
compare_url(base, head) the comparison's address
tag_url(tag) the tag or release view's address

Labels are spoken by name everywhere. configure ensures they exist; no separate label verbs exist.

The address family is pure string building: nothing goes on the wire and no address is probed for existence, so a changelog or a message can carry links without spending a request. Each backend writes its own path shapes (/pull/N on GitHub, /pulls/N on Gitea, /-/merge_requests/N on GitLab), which is why the shapes live here rather than in every caller. A built address is compared with a reported one by path, never by host: a server's links follow its own configured external address, which need not be the host the API was reached on (see quirks.md).

pr: pull requests

Verb Does
open(head, base, title, body) open; refuses a duplicate open head
find_by_head(branch, *, state) reliable for open pull requests
find_by_head_sha(sha) finds a merged pull request after its branch is gone; asked of the commit where the forge can
get(number) the pull request or None
list(*, state) every pull request in the state, newest first; closed holds the merged ones too, and each row is what get answers
update_title(number, title) the review-facing name and the future squash subject
update_body(number, body) the description, and the future squash message
close(number) / reopen(number) reopen reuses the pull request; a merged one refuses
merge_now(number, *, title, message) immediate merge; 405-shaped refusal when not green
arm(number, *, title, message) merge when green, server-side; disarm before any push
disarm(number) cancels the schedule; True when one existed
is_armed(number) the schedule's state; a non-open pull request reads unarmed
merge_hold(number) the forge's published mergeability state, verbatim (GitLab detailed_merge_status, GitHub mergeable_state); empty where none is published
reviews(number) the submitted review verdicts; drafts never arrive
schedule_events(number) the merge-scheduling history, oldest first; capability-gated (schedule_events)
comment(number, body) the evidence channel
add_labels(number, names) puts the named labels on the pull request, idempotent; a name the repository does not carry is refused by name before anything is written, on every backend, since GitHub and GitLab would otherwise create it. PullRequest.labels reads them back

The arming contract: pushing to an armed pull request races the server-side merge, and the merge can take the pre-push head. Disarm, push, re-arm. The merge itself is always observed, never performed by the waiting caller.

checks: CI

Verb Does
status(sha) the one combined verdict; none (nothing reported) is distinct from pending
runs(*, head_sha, event, workflow, limit) newest first; a workflow is asked of its own listing, and a limit stops the read at the newest
jobs(run) a run's jobs
job_log(job) the raw log; quoted verbatim in triage, never boolean-ised
rerun(run, *, failed_only=True) failed jobs by default; refuses a live run
cancel_run(run, *, force=False) required everywhere; refuses a terminal run; force is capability-gated
dispatch(workflow, *, ref, inputs) trigger a workflow; returns the run's id, which every backend's answer names, and None from a server whose answer names no run, where the caller finds the run in runs by its event, ref and head_sha

release: releases by tag

Verb Does
create(tag, *, name, body, prerelease) refuses a tag that already has a release
get(tag) the probe that makes release creation re-runnable
upload_asset(tag, name, data, *, content_type) attaches a file; refuses a name the release already carries
assets(tag) the files attached, each with its size and, where the forge computes one, its digest
download_asset(tag, name) the bytes back, read the way that forge serves them

issue: text in both directions

Verb Does
create(title, *, body, labels, assignee) the body is the work order; labels by name
get(number) body included, or None
list(*, state) issues only, never pull requests
search(text, *, state, labels) matches title and body; the deduplication probe
assign(number, assignee) adds to the assignees; a colleague's stays. How many an issue may carry is the caller's policy
unassign(number) removes only the authenticated user; not being assigned is a no-op
assigned_to_me() the open issues assigned to the token's user
comment(number, body) evidence the body cannot carry
comments(number) the thread back, oldest first: each comment's author, time and body; a forge's own system notes are left out
close(number) closes; closing a closed issue is a no-op, so re-running is the recovery

Registry: one method, apart from the forge

Verb Does
versions(name) the published versions of a package name; empty when unpublished

A forge and a registry are only sometimes the same server, so the index question is its own interface with a backend per ecosystem.

Testing against the protocol

Consumers test against livery.forge.testing.FakeForge, which passes the same conformance suite the real backends must pass. See fixtures.md for the record and replay layer, and quirks.md for the fault modes the fake injects. The GitLab endpoint mapping is in gitlab.md.