186 lines
8.5 KiB
Markdown
186 lines
8.5 KiB
Markdown
# 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.
|
|
|
|
## CI preparation
|
|
|
|
Use `PrepareTaggedCheckout` when a disposable CI checkout must be verified
|
|
against the commit that triggered the job. It fetches only the selected tag
|
|
from the chosen remote (default `origin`), compares the peeled tag commit with
|
|
the expected commit, and checks out that commit detached. Fetch or checkout
|
|
conflicts are returned so the caller can replace or repair the workspace.
|
|
Cancellation is returned to the caller; the operation does not publish a tag
|
|
or hosted content.
|
|
|
|
```go
|
|
err := releasekit.PrepareTaggedCheckout(ctx, releasekit.TaggedCheckoutRequest{
|
|
RepositoryDir: repositoryDir,
|
|
Version: version,
|
|
ExpectedCommit: ciCommit,
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
```
|
|
|
|
For binary profiles, call `PrepareBuildDependencies(ctx, repositoryDir)` after
|
|
checkout preparation and before delivery. It runs `go mod download` with
|
|
workspace discovery disabled and the available compatible local Go toolchain.
|
|
The operation may use the network and updates the Go module cache while
|
|
preserving the caller's proxy, private-module, credential, and cache settings.
|
|
If checksums are missing, Go may update `go.sum`; see the
|
|
[Go Modules Reference](https://go.dev/ref/mod#go-mod-download). Cancellation
|
|
and command errors are returned. Page-only profiles do not need dependency
|
|
preparation.
|
|
|
|
## Command line
|
|
|
|
Add a Gitea destination to the profile:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```sh
|
|
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,
|
|
one `deliver` invocation builds the tagged source through the facade into
|
|
temporary storage and delivers the result. To retain artifacts for a retry or
|
|
separate credentials between build and delivery, use two invocations:
|
|
|
|
```sh
|
|
releasekit build --output dist v1.2.3
|
|
RELEASEKIT_GITEA_TOKEN="$GITEA_TOKEN" releasekit deliver --assets dist v1.2.3
|
|
```
|
|
|
|
The build command does not need delivery credentials. The `--assets DIR`
|
|
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; caller-owned
|
|
files remain available for retries. Ordinary `deliver` does not download
|
|
application dependencies or change the checkout.
|
|
|
|
The result reports `complete`, `partial`, `conflict`, `unknown`, or
|
|
`not_attempted`, along with matching, uploaded, pending, conflicting, and
|
|
uncertain assets when known. These are disjoint current observations: an asset
|
|
appears in at most one category, and early failures may leave some declared
|
|
assets unreported. `Matching` means existing content matches; `Uploaded` means
|
|
an upload was confirmed during this invocation; `Pending` means known missing
|
|
work; `Conflicting` means different hosted content was found; `Uncertain` means
|
|
the remote state could not be resolved.
|
|
|
|
Fix local or preflight failures before retrying. For partial delivery, fix the
|
|
reported cause and retry the same version. Resolve an unknown remote outcome
|
|
before retrying. Investigate conflicts and use a new version if the source or
|
|
published content needs correction. If rebuilding could change bytes already
|
|
on the server, retain the original build output and retry with `--assets DIR`.
|
|
The command does not run candidate checks or publish tags.
|
|
|
|
## Go API
|
|
|
|
Pass the Gitea credential explicitly. Set `Build` to a `BuildSpec` to compile
|
|
selected targets as part of delivery. The facade verifies the local tag, clean
|
|
checkout, and committed release note before compiling. Managed output is stored
|
|
outside the checkout and removed when delivery returns. `Output` receives build
|
|
progress. With no build, or with an empty target set, delivery is page-only.
|
|
|
|
To deliver binaries built separately, set `Prebuilt` to the `BuildResult`.
|
|
ReleaseKit checks that it identifies the selected repository, tagged commit, and
|
|
version, that its source was verified clean and unchanged during compilation,
|
|
and that the current files still match their recorded digests. The files remain
|
|
caller-owned, so callers can retain the original bytes for retries and are
|
|
responsible for cleanup. With neither artifact source, an empty managed target
|
|
set, or an empty prebuilt result, delivery is page-only. Do not set both `Build`
|
|
and `Prebuilt` in one request.
|
|
|
|
```go
|
|
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,
|
|
},
|
|
Build: &releasekit.BuildSpec{
|
|
MainPackage: "./cmd/example",
|
|
BinaryName: "example",
|
|
Targets: []releasekit.Target{{OS: "linux", Arch: "amd64"}},
|
|
},
|
|
})
|
|
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](../cli.md), [configuration reference](../config.md),
|
|
and [Gitea integration guide](../integrations/gitea.md) for exact settings,
|
|
exit codes, and transport behavior.
|
|
|
|
## Woodpecker tag workflows
|
|
|
|
Maintained workflow examples are available for source-only and binary delivery:
|
|
|
|
- [Source-only tag workflow](../../examples/woodpecker/tag-delivery-source-only.yml)
|
|
- [Binary tag workflow](../../examples/woodpecker/tag-delivery-binary.yml)
|
|
|
|
Copy one into the consumer repository's `.woodpecker/` directory. In its
|
|
matrix entry, set `GO_IMAGE` to a Go image compatible with the consumer module
|
|
and replace `RELEASEKIT_SOURCE` with an immutable ReleaseKit commit. The
|
|
examples deliberately contain no claimed published ReleaseKit pin. Configure
|
|
the Woodpecker repository secret `releasekit_gitea_token`; the workflow maps it
|
|
to `RELEASEKIT_GITEA_TOKEN` only for the delivery step. The repository also
|
|
needs a `delivery` profile using the default `RELEASEKIT_GITEA_TOKEN` variable.
|
|
The binary profile must declare its build targets.
|
|
|
|
The tag workflow fetches the event tag, verifies that the tag resolves to
|
|
`CI_COMMIT_SHA`, and checks out that commit detached. Woodpecker shares the
|
|
repository workspace between sequential steps, so the installed executable
|
|
and Go caches remain available. The workflow keeps its `.releasekit/` directory
|
|
out of Git status using the checkout's local exclude file.
|
|
|
|
Preparation can access the Go module proxy to install the pinned ReleaseKit
|
|
executable. The binary workflow also runs `go mod download` before delivery.
|
|
The single `releasekit deliver` invocation builds selected targets through the
|
|
facade and uploads them with the release page. The source-only workflow sends
|
|
the committed note page directly. Neither template runs `check` or `publish`.
|
|
|
|
Woodpecker runs delivery after the tag event, independently from the source
|
|
publication result. Read its workflow status as delivery status: a delivery
|
|
failure does not undo source publication. A failed, partial, or uncertain run
|
|
can be inspected and retried against the same immutable tag and commit; do not
|
|
move the tag to make a retry pass. See
|
|
[Woodpecker's environment reference](https://woodpecker-ci.org/docs/usage/environment)
|
|
for the runner-provided tag and commit variables and
|
|
[workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax) for tag
|
|
events, sequential steps, and the shared workspace.
|