255 lines
14 KiB
Markdown
255 lines
14 KiB
Markdown
# Command line
|
|
|
|
ReleaseKit currently provides six 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 module, version, full tag, and commit. It checks the committed release note and
|
|
local Git state, runs the standard offline Go test suite (with `-race` when
|
|
`validation.go.race` is true), and runs a separate `go vet -mod=readonly ./...`
|
|
pass after successful tests when `validation.go.full_vet` is true. It then runs
|
|
selected package compilation and committed Go formatting, followed by
|
|
configured additional checks in profile order. It does not inspect remote
|
|
availability or publish a tag.
|
|
|
|
The profile's optional `module_dir` selects a repository-relative physical
|
|
module directory; omission selects the root module. Validation and configured
|
|
product checks use that module selection. Additional check commands run with
|
|
the selected module as their working directory and receive
|
|
`RELEASEKIT_VERSION`, `RELEASEKIT_CANDIDATE`, `RELEASEKIT_REPOSITORY_DIR`,
|
|
`RELEASEKIT_MODULE_DIR`, `RELEASEKIT_MODULE_PATH`, and `RELEASEKIT_TAG` in their
|
|
environment. These values are added to each child environment without changing
|
|
the ReleaseKit process environment.
|
|
|
|
When `validation.go.compile_targets` is selected, `check` compiles all packages
|
|
for each configured `GOOS/GOARCH` pair after tests and full vet, using static
|
|
mode with cgo disabled. This check produces no artifacts and does not execute
|
|
target binaries. Compilation failures use the `package-compile` identity and
|
|
show the selected target. When `validation.go_format` is true, `check` examines
|
|
regular committed Go files with the Go formatter after tests, vet, and package
|
|
compilation. It includes vendor and nested-module source, ignores the worktree
|
|
and symlink blobs, and reports unformatted paths as `go-format` without
|
|
modifying files. When `validation.module_distribution.workspace_files` is true,
|
|
`check` reports committed `go.work` and `go.work.sum` blobs, including nested
|
|
and symlink entries, as `workspace-files`. This inspection is independent of
|
|
`GOWORK` and ignores uncommitted files. Any artifact build selected by the
|
|
separate `build` setting runs after shared validation and configured checks.
|
|
When `validation.markdown` is a non-null object, `check` checks committed local
|
|
Markdown destinations and supported heading fragments after file-size
|
|
inspection. An empty object enables the check; omission or `null` disables it.
|
|
Outside-checkout links are written as out-of-scope observations to standard
|
|
error by default. Setting `validation.markdown.enforce_checkout_boundary` to
|
|
true makes those links fail; submodule-content observations remain
|
|
nonfailures. Failures use the `markdown-links` identity with the source location
|
|
and target.
|
|
|
|
`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. Shared validation failures identify the
|
|
failed check and retain useful findings and cause context in one diagnostic;
|
|
separate full-vet failures use the `go-vet` identity.
|
|
Unsupported argument sequences print usage to standard error.
|
|
|
|
Publish a source tag:
|
|
|
|
```sh
|
|
go run ./cmd/releasekit publish [--repo DIR] [--config FILE] [--expected-module DIR] VERSION
|
|
```
|
|
|
|
`publish` reads the same product, remote, validation, and additional-check
|
|
settings as `check`. It checks the authoritative remote and validates the
|
|
candidate: the single standard offline Go test suite runs first, with `-race`
|
|
when `validation.go.race` is true. When `validation.go.full_vet` is true,
|
|
test-time vet is disabled and `go vet -mod=readonly ./...` runs after successful
|
|
tests. Selected package compilation and committed Go formatting follow. The
|
|
selected file checks then run in order: workspace files, local replacements,
|
|
file size, and Markdown. Configured checks run afterward in profile order. It
|
|
then creates an annotated local tag
|
|
and pushes only its exact full tag object. It prints the confirmed semantic
|
|
version, full tag, 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.
|
|
Shared validation failures use the same check and finding presentation as
|
|
`check`, alongside publication state and phase.
|
|
|
|
When `validation.go.compile_targets` is selected, package compilation runs
|
|
after tests and full vet and before configured checks. Each failure is reported
|
|
as `package-compile` with its selected target; this does not create build
|
|
artifacts or execute target binaries. When `validation.go_format` is true,
|
|
committed Go formatting runs after package compilation and before configured
|
|
checks. The selected workspace-file check then reports committed go.work and
|
|
go.work.sum paths as `workspace-files`. Formatting failures are reported as
|
|
`go-format` with affected paths and preserve parser or source-inspection causes.
|
|
|
|
When `validation.module_distribution.local_replacements` is true, the command
|
|
parses committed `go.mod` declarations in the selected module after
|
|
workspace-file inspection. Vendored contents remain in scope, while
|
|
independently released nested modules are excluded. Filesystem replacements use
|
|
the `local-replacements` identity and include the declaration path, source line,
|
|
and target; versioned replacements are permitted. Committed module symlinks are
|
|
resolved within the candidate, regardless of `GOWORK`.
|
|
When `validation.file_size` is a non-null object, the command checks each
|
|
committed blob after module-distribution checks. An omitted or null object
|
|
disables the check; an empty object enables the 1,000,000 decimal-byte default.
|
|
Oversized files use the `file-size` identity and report their path and measured
|
|
size against the limit. See the [configuration reference](config.md) for
|
|
literal exclusions and the current-candidate scope.
|
|
When `validation.markdown` is a non-null object, `publish` checks committed
|
|
Markdown destinations after file-size inspection and before configured checks.
|
|
It reports outside-checkout links to standard error unless boundary enforcement
|
|
is selected; submodule contents remain out of scope. Markdown failures stop
|
|
publication before product checks or tag creation.
|
|
|
|
`--expected-module DIR` optionally checks a launcher's selected physical module
|
|
against the profile's `module_dir` before candidate work. Both paths are
|
|
normalized relative to the repository; the profile remains the source of module
|
|
selection. The root selection is `.`.
|
|
|
|
The optional profile field `expected_push_url` applies only to `publish`. A
|
|
nonempty value must exactly match the effective push URL resolved by Git;
|
|
mismatches fail during preflight before Go validation or tag creation. Git URL
|
|
rewrites are resolved first, and the push URL is used when fetch and push URLs
|
|
differ. `check` ignores this field.
|
|
|
|
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 selected module directory. 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` 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
|
|
when a remote write remains uncertain. The result lists matching, uploaded,
|
|
pending, conflicting, and uncertain assets as disjoint current observations;
|
|
early failures may leave some declared assets unreported. On failure, the CLI
|
|
prints state-based recovery guidance. Fix local or preflight failures before
|
|
retrying; fix the reported cause before retrying partial delivery; resolve an
|
|
unknown remote state before retrying; and investigate conflicts, using a new
|
|
version if the source or published contents need correction. If rebuilding
|
|
could change asset bytes already on the server, retain the original build
|
|
artifacts and retry with `--assets DIR`. Matching content is kept and only
|
|
known missing assets are added. See the
|
|
[delivery consumer guide](consumers/delivery.md) and
|
|
[Gitea integration guide](integrations/gitea.md).
|
|
|
|
Prepare a tagged CI checkout and deliver it:
|
|
|
|
```sh
|
|
releasekit ci-deliver [--repo DIR] [--config FILE] [--remote NAME] [--prepared] [--expected-module DIR] --commit OID TAG
|
|
```
|
|
|
|
`TAG` is the complete Git tag name, including any module path prefix. Its last
|
|
path component must be a stable semantic version; other commands continue to
|
|
take a semantic `VERSION`. By default, `ci-deliver` fetches the exact `TAG` from
|
|
the selected Git remote (default `origin`), requires its peeled commit to match
|
|
the required full `--commit` object ID, checks out that commit detached, then
|
|
verifies the tag, HEAD, and clean worktree. With `--prepared`, it performs those
|
|
checks read-only against the existing checkout and does not fetch or check out.
|
|
In either mode, it loads the profile from the verified source. `--expected-module`
|
|
optionally checks that the profile selects the module chosen by a launcher;
|
|
module selection itself remains profile-owned. The command validates delivery
|
|
settings and the configured token, then downloads application dependencies only
|
|
when the profile selects build targets. Binary profiles are built and delivered
|
|
through the same facade path as `deliver`; source-only profiles skip dependency
|
|
downloads and binary builds.
|
|
`--config` follows the existing profile path rules: relative paths are resolved
|
|
from `--repo`, and absolute paths are used as-is. The default mode prepares and
|
|
changes the selected checkout; `--prepared` reuses a verified checkout.
|
|
Ordinary `deliver` continues to operate on already prepared source without
|
|
fetching, checking out, or downloading dependencies.
|
|
|
|
In Woodpecker, pass `CI_WORKSPACE`, `CI_COMMIT_SHA`, and `CI_COMMIT_TAG` as the
|
|
repository, expected commit, and full tag arguments. The CLI does not read
|
|
provider-specific environment variable names. Checkout and dependency
|
|
preparation failures return status 1; usage, profile, credential, and invalid
|
|
version errors return status 2. Final delivery uses the same statuses as
|
|
`deliver`: 0 for complete, 1 for known failure, conflict, or partial delivery,
|
|
and 3 for uncertain remote state.
|
|
|
|
The maintained module-based tag workflow verifies and checks out the event tag
|
|
before resolving the consumer module. It builds the ReleaseKit version already
|
|
selected by that tagged `go.mod`, using temporary alternate module files outside
|
|
the source checkout. This tool bootstrap is separate from `ci-deliver`'s
|
|
application dependency preparation for binary profiles. ReleaseKit's own
|
|
source workflow self-bootstraps `./cmd/releasekit`; consumers without a declared
|
|
ReleaseKit module dependency can use the separately installed-tool command.
|
|
See the [delivery guide](consumers/delivery.md#woodpecker-tag-workflows) for
|
|
compatible Go environments, retries, and preparation details.
|