209 lines
11 KiB
Markdown
209 lines
11 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 local commit and version. 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.
|
|
|
|
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.
|
|
|
|
`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] 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 workspace-file check then runs, followed by configured checks in
|
|
profile order. It then 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.
|
|
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, including nested and vendor modules,
|
|
after workspace-file inspection. 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.
|
|
|
|
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 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` 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] --commit OID VERSION
|
|
```
|
|
|
|
`ci-deliver` fetches `VERSION` from the selected Git remote (default `origin`),
|
|
requires the tag's peeled commit to match the required full `--commit` object
|
|
ID, and checks out that commit detached. It then loads the profile from the
|
|
prepared checkout, validates delivery settings and the configured token, and
|
|
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. This command explicitly
|
|
prepares and changes the selected 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 version 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.
|