109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
# Command line
|
|
|
|
ReleaseKit currently provides five commands. The exit statuses below belong
|
|
to the native executable. `go run` examples are convenient for source execution,
|
|
but the Go driver maps a nonzero child exit status to 1. Use the built executable
|
|
or `./scripts/release` for publication when distinct statuses are needed.
|
|
|
|
Print the executable version:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit version
|
|
```
|
|
|
|
This prints `releasekit <version>` followed by a newline and exits with status 0.
|
|
The version comes from [`buildinfo.Version`](consumers/runtime-version.md).
|
|
|
|
Check a local candidate:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit check [--repo DIR] [--config FILE] VERSION
|
|
```
|
|
|
|
`VERSION` must use stable `vMAJOR.MINOR.PATCH` syntax. Options must precede the
|
|
version. The repository defaults to the current directory, and the profile
|
|
defaults to `<repository>/releasekit.json`. A successful command prints the
|
|
captured local commit and version. It checks the committed release note, local
|
|
Git state, and configured validation, but does not inspect remote availability
|
|
or publish a tag.
|
|
|
|
`check` writes errors and diagnostics to standard error. It returns status 0
|
|
after local validation, 1 after a candidate validation failure, and 2 for usage,
|
|
profile, or invalid-version errors. Unsupported argument sequences print usage
|
|
to standard error.
|
|
|
|
Publish a source tag:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit publish [--repo DIR] [--config FILE] VERSION
|
|
```
|
|
|
|
`publish` reads the same product, remote, and validation settings as `check`.
|
|
It validates the candidate once, checks the authoritative remote, creates an
|
|
annotated local tag, and pushes only its exact tag object. It prints the
|
|
confirmed version, candidate commit, and tag object on success. Validation
|
|
progress and failed publication state, including the captured publication
|
|
endpoint for recovery, are written to standard error. A signal
|
|
cancels the active operation; if it arrives during a push, the library's
|
|
bounded reconciliation determines whether the exact tag was accepted.
|
|
|
|
The command returns status 0 for confirmed publication, 1 for a known
|
|
publication failure or conflict, 2 for usage, profile, or invalid-version
|
|
errors, and 3 when the push outcome remains unknown. Unknown status must be
|
|
resolved against the authoritative remote before retrying. The
|
|
[maintainer procedure](release.md) selects the repository profile and gives
|
|
the source-release workflow.
|
|
|
|
Build selected application targets:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit build [--repo DIR] [--config FILE] [--output DIR] VERSION
|
|
```
|
|
|
|
`build` requires a `build` object in the profile. It compiles the selected
|
|
targets with the requested version injected, checks the native `version`
|
|
invocation, and writes binaries plus the private `.releasekit-build.json`
|
|
receipt into `dist` by default. `--output` selects a different directory;
|
|
relative paths are resolved from the repository. Selected artifact filenames
|
|
are regenerated while unrelated files are preserved. A complete nonempty build
|
|
writes a receipt only after compilation and smoke checking succeed. On partial
|
|
failure, standard error lists completed outputs and prior receipts in that
|
|
output directory are invalidated; no new receipt is written. An
|
|
empty target list returns the source commit without building or writing a
|
|
receipt.
|
|
|
|
The command returns status 0 on completion, 1 for build or output failure, and
|
|
2 for usage, profile, or invalid-version errors. It builds the current source
|
|
tree and does not perform candidate validation or remote publication. `check`
|
|
and `publish` run the same configured build after their one candidate
|
|
validation, using temporary output outside the worktree.
|
|
|
|
Deliver a tagged source release to Gitea:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit deliver [--repo DIR] [--config FILE] [--assets DIR] VERSION
|
|
```
|
|
|
|
`deliver` requires a `delivery` profile object and its configured token
|
|
environment variable, which defaults to `RELEASEKIT_GITEA_TOKEN`. It verifies
|
|
the local tag, clean tagged checkout, hosted tag, and committed release note,
|
|
then creates or finds the release page and reports delivery state separately
|
|
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.
|
|
|
|
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
|
|
when a remote write remains uncertain. The result lists matching, uploaded,
|
|
pending, conflicting, and uncertain assets as available. Retry the same version
|
|
with the same tagged source and destination; matching content is kept and only
|
|
missing assets are added. See the [delivery consumer guide](consumers/delivery.md)
|
|
and [Gitea integration guide](integrations/gitea.md).
|