Releases

What a release is

A release is an annotation on a tag that already exists. Push the tag through the ordinary push path, then publish the release against it. Creating a release writes one row and no ref: it never creates or moves a tag, so it is not a second door past the gate that decides what a ref may point at.

A release names its tag and the commit it pins. If the tag does not point at that commit when the release is written, the release is refused (tag moved), so a tag that moved between the screen rendering and the button being pressed cannot be released by mistake. A tag holds at most one release.

The proof rule

Before a release is written, the signed merge records for the pinned commit are read and verified. The outcome is one of five, and the screen shows it on every release:

The acknowledgement is consent to ship unproved bytes, not consent to ship bytes whose proof the server could not read: a tampered record and a failed lookup refuse whatever the caller says. An acknowledged release shows Unproven, acknowledged with the reason and the name of who gave it. A break-glass landing is not folded into failure; it is read from the signed record, and it needs the same acknowledgement.

POST /orgs/{space}/repos/{repo}/releases
{"tag": "v1.2.0", "commit": "<sha>", "title": "1.2.0", "notes": "…",
 "unproven_acknowledged": false}

The release page lists the signed merges on the pinned commit by landing sequence. A release imported from GitHub is always published as acknowledged, with the import as its reason: its commit was proved, if at all, on another server.

Release notes

Notes can be generated from the signed merge records between the previous release's commit and this one. The repository's .sigbound/release-notes.conf names the headings and the landing verdicts each collects; each entry is one landing with its ref, verdict, checks, approver and, when it applies, its break-glass flag. Records that did not verify are listed under their own heading, Merge records that did not verify. Generation refuses when the repository has no earlier release or when either boundary commit has no verified merge record, and is bounded at 50 entries.

POST /orgs/{space}/repos/{repo}/release-notes

Assets

A release holds up to 100 assets. An asset is declared up front with its name, size and SHA-256, then uploaded in chunks at offsets, and an interrupted upload resumes from the number of bytes the server has. The asset exists only if the assembled bytes hash to the declared digest; a mismatch is discarded and refused. The digest the API reports is the one the server computed over the bytes it serves. A single asset may be up to 2 GiB, subject to the repository's storage quota.

Channels

A release can be promoted onto a named channel, such as staged, canary or stable; a channel points at its current release, and a consumer reads the channel rather than a tag. A channel name is lowercase, up to 64 characters. A release may sit on up to 16 channels and a repository may hold up to 100.

GET  /orgs/{space}/repos/{repo}/release-channels
POST /orgs/{space}/repos/{repo}/release-channels
GET  /orgs/{space}/repos/{repo}/release-channels/{channel}

The releases screen

Releases in the repository header lists releases newest first with the marker on each. New release takes the tag in short form, the commit, a title and notes, and the acknowledgement with its reason when the marker requires one. Publishing, promoting and generating notes need repository policy authority; reading needs read.