ReleaseKit/docs/consumers/delivery.md

Deliver a tagged source release

Use releasekit.Deliver or the deliver command after a source tag exists. Delivery status is separate from source publication: a delivery problem does not move or remove the tag, and a retry can use the same immutable version. The operation accepts historical lightweight and annotated tags, including a detached checkout, when the checked-out HEAD identifies the selected tag commit. It does not require the old remote main to match.

Command line

Add a Gitea destination to the profile:

{
  "product": "Example",
  "delivery": {
    "base_url": "https://gitea.example",
    "owner": "example",
    "repository": "example",
    "token_env": "RELEASEKIT_GITEA_TOKEN"
  }
}

Fetch and check out the immutable tag, then deliver it:

git checkout --detach v1.2.3
RELEASEKIT_GITEA_TOKEN="$GITEA_TOKEN" releasekit deliver v1.2.3

The CLI reads the named token variable only for deliver; its default name is RELEASEKIT_GITEA_TOKEN. It verifies the local checkout and hosted tag before creating or accepting a hosted release page. The full checked-in note is the hosted body. A retry accepts an identical page and matching attachments, adds only missing assets, and reports conflicts without replacing content.

With no build targets, delivery is page-only: no builder, version smoke check, receipt, binary asset, or checksum manifest is involved. With selected targets, the command builds the tagged source into temporary storage and delivers the result. To use artifacts built separately, pass --assets DIR; the directory must contain the private .releasekit-build.json receipt created by build. ReleaseKit checks the receipt's repository, commit, version, resolved build settings, and file hashes before making a remote request.

The result reports complete, partial, conflict, unknown, or not_attempted, along with matching, uploaded, pending, conflicting, and uncertain assets when known. Exit status 3 means a remote write could not be resolved; inspect the same version and retry only after the remote state is understood. The command does not run candidate checks or publish tags.

Go API

Pass the Gitea credential explicitly. A BuildResult may be supplied for a binary-producing release; it must identify the same tagged repository commit and selected version, and its local artifacts must still match their digests. Leave Build nil for a source-only release.

result, err := releasekit.Deliver(ctx, releasekit.DeliveryRequest{
    RepositoryDir: "/work/example",
    Product:       "Example",
    Version:       "v1.2.3",
    Destination: releasekit.GiteaDestination{
        BaseURL:    "https://gitea.example",
        Owner:      "example",
        Repository: "example",
        Token:      token,
    },
})
if err != nil {
    // Keep the returned state and any completed asset identities for recovery.
    return err
}
fmt.Println(result.State, result.ReleaseURL)

See the CLI contract, configuration reference, and Gitea integration guide for exact settings, exit codes, and transport behavior.