3.8 KiB
Gitea release pages
ReleaseKit's public Deliver operation and deliver command verify tagged
source, find or create its stable release page, inspect existing assets, and
upload missing assets through the internal Gitea client. Page-only and
binary-producing profiles use the same delivery path. The
consumer delivery guide covers caller workflows;
this guide describes the Gitea protocol and its failure behavior.
The caller supplies the Gitea base URL, owner, repository name, and token
explicitly. The client does not read ambient credentials. The token is sent in
the Authorization: token … request header and is not included in errors or
results. The base URL must use HTTP or HTTPS and cannot contain URL credentials,
a query, or a fragment.
For version vMAJOR.MINOR.PATCH, the client first reads
/api/v1/repos/{owner}/{repo}/tags/{tag} and requires the hosted tag's commit
SHA to equal the captured source commit. It then reads
/api/v1/repos/{owner}/{repo}/releases/tags/{tag}. A matching existing page
must have that tag, the complete committed release note as its body, and stable
non-draft state. Its existing title is retained. ReleaseKit does not edit a
conflicting page.
If the page is absent, the client posts to /api/v1/repos/{owner}/{repo}/releases
with the selected tag and commit, the release note's H1 as title, the complete
note as body, and draft and prerelease disabled. A create conflict, interrupted
response, or malformed create response triggers one lookup. An exact page found
there confirms the existing content; a differing page is a conflict. If that
lookup cannot determine the result after a possibly successful write, the
client returns an unknown outcome. Other HTTP failures retain their structured
failure kind and status code.
For a binary-producing release, the client can build a deterministic
SHA256SUMS file from the declared artifact names and SHA-256 digests. Entries
are sorted by filename and use the standard two-space separator. A source-only
release produces no manifest.
Asset inspection lists the release attachments, streams each declared existing
file, and compares its SHA-256 digest. It reports each asset as matching,
missing, conflicting, or unverifiable. Same-name attachments with different
bytes are conflicts even when their reported size matches. An existing
SHA256SUMS must exactly match the complete expected manifest; a subset or
different manifest is a conflict. An unreadable attachment is unverifiable,
not missing. Unrelated attachments are returned separately and are preserved.
Attachment downloads and same-origin redirects carry authorization only when their scheme, host, and port match the configured Gitea service. Cross-origin URLs and redirects are left unrequested and reported as unverifiable.
The upload operation accepts only an inspection result without conflicts or
unverifiable assets. It uploads missing binaries in filename order and then the
missing SHA256SUMS, using multipart field attachment and the filename query
parameter name. Matching attachments are retained; unrelated and existing
attachments are never overwritten or deleted. Results keep matching, uploaded,
pending, conflicting, and uncertain identities separate. After an ambiguous
upload or an upload name conflict, the client performs one list and content
check. It does not repeat the POST when the result is missing or cannot be
verified, so a caller can retry with a new inspection.
Uploads use the configured service origin and the same explicit token header. Source-only page delivery supplies no binary assets and creates no manifest.
The integration tests use a local HTTP fixture and assert request paths, payloads, authorization, streaming comparisons, manifest handling, and failure handling. They do not contact a live Gitea service or use real credentials.