eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Route CLI delivery through the facade

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 18:35:45 +00:00
parent a67a00a733
commit 579daa9485
9 changed files with 108 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/cli.md
View File

@@ -95,12 +95,21 @@ from source publication. Historical lightweight tags and detached checkouts
are supported when `HEAD` is the selected tag commit; delivery does not require
the former remote `main` to match.
When the profile has build targets and `--assets` is omitted, `deliver` builds
the tagged source into temporary storage and uploads its binaries and complete
`SHA256SUMS`. When `--assets DIR` is supplied, that directory must contain the
private `.releasekit-build.json` receipt and matching unchanged artifacts.
Profiles without targets use page-only delivery and need no receipt, binary
build, or manifest. `deliver` never runs candidate checks or publishes a tag.
When the profile has build targets and `--assets` is omitted, `deliver` passes
the configured build directly to the public delivery facade. The facade builds
the tagged source into temporary storage, removes it when the operation ends,
and uploads its binaries and complete `SHA256SUMS`. When `--assets DIR` is
supplied, that directory must contain the private `.releasekit-build.json`
receipt and matching unchanged artifacts; this keeps the caller's original
bytes available for retries. Profiles without targets use page-only delivery
and need no receipt, binary build, or manifest. `deliver` never runs candidate
checks or publishes a tag.
Use one `deliver` invocation for the normal workflow. To build without delivery
credentials, or to retain build output across retries, run `build --output DIR`
first and then run `deliver --assets DIR` with the token available. The ordinary
`deliver` command does not download application dependencies or change the
checkout.
The command returns 0 for complete delivery, 1 for a known failure, conflict,
or partial delivery, 2 for usage, profile, or missing-credential errors, and 3

12
docs/config.md
View File

@@ -39,10 +39,14 @@ as an additional product check. Selected-target builds run after both. Do not
repeat the standard suite in `checks`; doing so runs it twice. The `build`
command uses the selected build settings and writes binaries to `dist` unless
`--output` selects another path.
The `deliver` command uses the delivery destination and token, then either
builds selected tagged-source targets into temporary storage or loads verified
assets from the directory selected by `--assets`. An absent build object or an
empty target set selects page-only delivery.
The `deliver` command uses the delivery destination and token. By default it
passes selected targets to the delivery facade, which builds tagged-source
artifacts into temporary storage and removes them when delivery returns. An
absent build object or an empty target set selects page-only delivery. Use
`build --output DIR` followed by `deliver --assets DIR` when artifacts must be
retained for retries or when build and delivery credentials need separate
invocations. Ordinary `deliver` does not download application dependencies or
change the checkout.
ReleaseKit's source-only profile is
[releasekit.json](../releasekit.json).

37
docs/consumers/delivery.md
View File

@@ -38,11 +38,21 @@ 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.
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
@@ -123,18 +133,15 @@ 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,
Go caches, build outputs, and build receipt remain available to later steps.
The workflow keeps its `.releasekit/` directory out of Git status using the
checkout's local exclude file.
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 the build.
The later `releasekit build` command runs with `GOPROXY=off` and
`GOTOOLCHAIN=local`; its declared binary targets and receipt are placed in
`.releasekit/assets`. Delivery then passes that directory with `--assets`.
The source-only workflow skips this build step and sends the committed note
page directly. Neither template runs `check` or `publish`.
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

12
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# ReleaseKit audit implementation plan
Status: Stages 1–6 complete; Stage 7 next.
Status: Stages 1–7 complete; Stage 8 next.
Baseline: `e4be7fa` (2026-10-06). The [audit](audit.md) records the evidence,
product goals, and selected direction. This document owns implementation order
and completion criteria for that work.
@@ -364,6 +364,16 @@ preflight failure before compilation, token/profile errors, and the explicit
receipt path. Reuse Stage 6 for domain failure coverage. Confirm the maintained
ordinary command exercises the facade-owned lifecycle and reports F7's results.
**Completed:** Ordinary `deliver` now passes configured builds and progress
output directly to the public facade; the CLI retains profile, credential,
receipt, presentation, and exit-status handling. `--assets` still validates
the private receipt and supplies caller-owned artifacts. CLI tests cover
page-only and binary profiles, preflight rejection before build progress,
retained prebuilt artifacts, retry observations, and temporary-output cleanup.
The binary workflow and consumer guidance use one `deliver` invocation by
default and explain the separate `build`/`--assets` path. The full offline suite,
API boundary check, and documentation whitespace checks pass.
## Stage 8 — Add reusable CI preparation operations
**Covers:** preparation ownership in F6. **Primary owners:** a new root