4.4 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 (including inconsistent decoded fields)
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. A recovered create retains its write history;
a later asset-inspection failure reports partial page progress.
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. A failed read-only inspection reports not_attempted; if this
invocation already delivered the page, its outcome retains partial progress.
Unknown-write outcomes are reserved for unresolved writes. Unrelated attachments are returned separately and are preserved.
Attachment downloads and redirects carry the Gitea authorization token only when their scheme, host, and port match the configured service. Cross-origin content is downloaded without that token and verified by its digest.
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 use disjoint current
observations: matching, uploaded, pending, conflicting, and uncertain. An asset
moved from known missing work to another category is removed from pending;
later known-missing assets can remain pending when an earlier upload stops the
operation. Early failures may leave declarations unreported. 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 resolve the remote state before retrying.
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.