From a4b82c28075067772da5785ea846d8c1e19a5375 Mon Sep 17 00:00:00 2001 From: Joshua Gilman Date: Thu, 20 Aug 2026 14:27:46 -0700 Subject: [PATCH] docs(cli): document native mise installation --- README.md | 1 + docs/how-to/install-release-cli-with-mise.md | 87 ++++++++++++++++++++ docs/reference/github-release-contract.md | 2 +- docs/reference/release-cli-contract.md | 5 ++ 4 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 docs/how-to/install-release-cli-with-mise.md diff --git a/README.md b/README.md index b4bbf1a..0504ce3 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ This repository defines the reusable workflows and repository contract that Meig ## Documentation +- [Install `release-cli` with mise](docs/how-to/install-release-cli-with-mise.md) - [Configure GitHub releases](docs/how-to/configure-github-releases.md) - [Configure OCI image publication](docs/how-to/configure-oci-images.md) - [Rehearse and recover GitHub releases](docs/how-to/rehearse-and-recover-github-releases.md) diff --git a/docs/how-to/install-release-cli-with-mise.md b/docs/how-to/install-release-cli-with-mise.md new file mode 100644 index 0000000..9e506c3 --- /dev/null +++ b/docs/how-to/install-release-cli-with-mise.md @@ -0,0 +1,87 @@ +# Install `release-cli` with mise + +Use mise's built-in GitHub backend to install a tagged `release-cli` release. The +current release does not require a mise plugin or a custom installer. + +This guide is for direct command-line use. Repositories that call the reusable +Meigma release workflows do not install or version `release-cli` separately. +The pinned workflow revision selects and verifies the matching CLI release. + +## Install a project version + +From the project directory, install the current release: + +```bash +mise use github:meigma/release@0.1.2 +``` + +Mise writes this tool entry to the project's `mise.toml`: + +```toml +[tools] +"github:meigma/release" = "0.1.2" +``` + +Verify the installed command: + +```bash +mise exec -- release-cli version --json +``` + +The current release reports: + +```json +{ + "schema": "release.dev/result/v1", + "command": "version", + "ok": true, + "result": { + "version": "0.1.2", + "commit": "611195c21fdd44ff2cf95c6a8833f84d095270b0", + "protocol": 1 + } +} +``` + +Mise selects the release archive for the host operating system and architecture. +The `v0.1.2` release contains archives for Darwin, Linux, and Windows on `amd64` +and `arm64`. During a verified installation, mise reports the selected archive, +its checksum check, and GitHub artifact attestation verification. + +## Run without changing project configuration + +Use `mise x` for a temporary invocation: + +```bash +mise x github:meigma/release@0.1.2 -- release-cli version --json +``` + +## Install for your user account + +Add `-g` to write the tool entry to the global mise configuration: + +```bash +mise use -g github:meigma/release@0.1.2 +mise exec -- release-cli version --json +``` + +Pin an explicit version in project and automation configuration. Update the +version deliberately after verifying the target GitHub Release. + +## Use a local shorthand + +`release-cli` is not registered in the mise registry. The full backend name is +therefore required by default; `mise use release-cli@0.1.2` does not resolve. + +To define a local shorthand, add an alias and tool entry: + +```toml +[tool_alias] +release-cli = "github:meigma/release" + +[tools] +release-cli = "0.1.2" +``` + +The alias affects only the mise configuration that defines it. It does not +publish `release-cli` to the shared mise registry. diff --git a/docs/reference/github-release-contract.md b/docs/reference/github-release-contract.md index 29ac121..e106a40 100644 --- a/docs/reference/github-release-contract.md +++ b/docs/reference/github-release-contract.md @@ -389,7 +389,7 @@ An undraft request has no rollback. A failure from the undraft call is indetermi This contract does not provide or imply: - OCI construction or publication behavior beyond the dependency ordering defined here; see the separate [OCI image contract](oci-image-contract.md). -- Homebrew, MacPorts, Nix, Scoop, mise registry, or other package-manager publication. +- Homebrew, MacPorts, Nix, Scoop, mise registry, or other package-manager publication. Tagged `release-cli` archives remain installable through mise's built-in GitHub backend; see [Install `release-cli` with mise](../how-to/install-release-cli-with-mise.md). - Native package repository publication or native package-manager signing. DEB, RPM, and APK files are standalone GitHub Release assets protected by the release checksum, Cosign, and attestation contract. - Release support for languages other than the documented Go producer profile. - Consumer CI policy or tests in the OIDC-enabled release job. diff --git a/docs/reference/release-cli-contract.md b/docs/reference/release-cli-contract.md index 569bbed..468c9d3 100644 --- a/docs/reference/release-cli-contract.md +++ b/docs/reference/release-cli-contract.md @@ -797,6 +797,11 @@ The projection records staged facts only. The image builder recomputes each dige The reusable workflows, `.github/actions/setup-release-cli`, and `release-cli` form one release unit and share one version. The producer loads the sibling action with `uses: ./.github/actions/setup-release-cli`. A consumer pins the workflow at one full commit SHA, and that self-reference selects the action from the same commit and its stamped default CLI version. The current released pin is `611195c21fdd44ff2cf95c6a8833f84d095270b0` (`v0.1.2`). Consumers cannot select an independent CLI version. +Direct CLI users can install a tagged release through mise's built-in GitHub +backend. See [Install `release-cli` with mise](../how-to/install-release-cli-with-mise.md). +This installation path does not change the release-unit pin used by reusable +workflow consumers. + The setup action has two optional inputs: | Input | Required | Meaning |