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

Verify tag-selected tool versions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 23:41:25 +00:00
parent b80d4ee071
commit eee979db7b
7 changed files with 314 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/cli.md
View File

@@ -220,3 +220,13 @@ 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.

8
docs/config.md
View File

@@ -181,6 +181,14 @@ dependencies. This preparation may access the network and may update
independent of Woodpecker environment variable names. See the
[CLI contract](cli.md) for the invocation and exit statuses.
This application dependency preparation is separate from bootstrapping the
ReleaseKit executable. The maintained module-based tag workflow verifies the
tag first, then uses temporary copies of that tag's module files to build the
ReleaseKit version selected by the consumer's `go.mod`. The
[delivery guide](consumers/delivery.md#woodpecker-tag-workflows) describes that
bootstrap, the self-bootstrapped source workflow, and the separately installed
tool option.
ReleaseKit's source-only profile is
[releasekit.json](../releasekit.json).
See the [source-only profile](../examples/releasekit.json) and

59
docs/consumers/delivery.md
View File

@@ -150,28 +150,44 @@ exit codes, and transport behavior.
Use the maintained [tag-delivery workflow](../../examples/woodpecker/tag-delivery.yml)
in the consumer repository's `.woodpecker/` directory. Set `GO_IMAGE` to an
image with Go 1.25 or newer, Git, and a Go version compatible with the consumer
module. Replace `RELEASEKIT_VERSION` with an immutable ReleaseKit revision or
published version. The example selects the initial `v0.1.0` baseline; update
that pin when adopting a later release. Configure the Woodpecker repository secret
`releasekit_gitea_token`; the template maps it to `RELEASEKIT_GITEA_TOKEN` only
for the delivery step. The repository needs a `delivery` profile. Page-only and
binary behavior both use this template; the profile's build target list selects
whether binaries are built and delivered.
image with Go 1.25 or newer, Git, and a local Go version compatible with the
consumer module. It uses `GOTOOLCHAIN=local`; Go does not download a different
toolchain. The tag's `go.mod` must select ReleaseKit as a module dependency.
Configure the Woodpecker repository secret `releasekit_gitea_token`; the
template maps it to `RELEASEKIT_GITEA_TOKEN` for delivery. The repository needs
a `delivery` profile. Page-only and binary behavior both use this template; the
profile's build target list selects whether application binaries are built and
delivered.
The command runs versioned source directly with `go run`, passing
`CI_WORKSPACE`, `CI_COMMIT_SHA`, and `CI_COMMIT_TAG` as command arguments.
`ci-deliver` fetches and verifies the event tag against its commit before
checking out the commit detached. It then loads the profile from that source,
validates the destination and token, and downloads application dependencies
only for profiles with build targets. The facade builds and delivers those
targets with the note page. Source-only profiles skip dependency downloads and
binary work. The workflow does not repeat checkout guards or maintain a
separate build/receipt/delivery sequence.
Before running Go, the template fetches the explicit event tag, compares its
peeled commit with the provider's full commit ID without regard to hex case,
checks out that commit detached, and confirms the source tree is clean. It then
copies the tagged `go.mod` and any `go.sum` to a temporary directory outside
the checkout. `go list -m` confirms that the module selects ReleaseKit; Go uses
an alternate `-modfile` to prepare dependencies and build the selected
`cmd/releasekit` package without changing the tagged module files. The template
invokes that executable with `CI_WORKSPACE`, `CI_COMMIT_SHA`, and
`CI_COMMIT_TAG`. A cleanup trap removes the temporary metadata and executable.
Tool bootstrap and application artifact preparation are separate. The bootstrap
resolves and builds ReleaseKit from the tagged consumer's module configuration.
Afterward, `ci-deliver` loads the profile and downloads application dependencies
only when build targets are selected; it builds and delivers those targets with
the note page. Source-only profiles skip application dependency downloads and
binary work. Dependency preparation for binaries may use the network and may
update an uncommitted checksum file in the checkout. A retry still uses the
same immutable tag and that tag's module settings, even after the default branch
selects a newer ReleaseKit version.
If the application does not declare ReleaseKit as a module dependency, install
the executable separately and invoke the same `ci-deliver` command. For
ReleaseKit's own source workflow, the maintained
[source-delivery template](../../examples/woodpecker/releasekit-source-delivery.yml)
checks out the tag and self-bootstraps `./cmd/releasekit` into temporary storage.
The normal Go module and build caches are sufficient. Cache mounts may be added
as deployment configuration when they help the runner; they are not needed by
the template. A locally retained executable can be installed with
the template. A separately installed executable can be installed with
`go install gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@PIN`, then run
with the same arguments:
@@ -179,9 +195,10 @@ with the same arguments:
releasekit ci-deliver --repo "$CI_WORKSPACE" --commit "$CI_COMMIT_SHA" "$CI_COMMIT_TAG"
```
Upgrade by changing the selected immutable
`RELEASEKIT_VERSION` (or the `@PIN` used by `go install`) and validating the
workflow against a tag fixture. The command and profile behavior are documented
The module-based workflow follows the ReleaseKit version selected by the tagged
consumer's `go.mod`, so retries use that source's original selection. Update the
consumer module configuration when adopting a newer ReleaseKit version and
verify it with a tag fixture. The command and profile behavior are documented
in the [CLI contract](../cli.md) and [configuration reference](../config.md).
Woodpecker runs delivery after the tag event, independently from the source

9
docs/roadmap/implementation.md
View File

@@ -547,6 +547,15 @@ and propagation of its exit status. Existing delivery tests own hosted behavior.
## Stage 13: Verify upgrades, retries, and bootstrap variants
**Completion:** Complete. The tag workflow is exercised against a local module
proxy with two tool versions, an older tagged configuration after the default
branch upgrades, and a versioned replacement. Missing tool-only dependency
checksums are prepared in temporary module metadata. The ReleaseKit source
workflow verifies its tag before self-bootstrap and writes the executable
outside the checkout. Delivery, configuration, and CLI guidance now distinguish
tool bootstrap from application dependency preparation and describe
immutable-source retries and installed-tool use.
**Outcome:** Tool selection follows the triggering release across supported uses.
1. Extend Stage 12's bootstrap fixtures with a local module proxy for two tool