ReleaseKit/docs/consumers/check.md

Local candidate check

Use releasekit.Check to verify a candidate against the current local repository state:

result, err := releasekit.Check(ctx, releasekit.ReleaseRequest{
	RepositoryDir: "/work/project",
	Product:       "Example",
	Version:       "v1.2.3",
	Validation: releasekit.ValidationSpec{
		Go: releasekit.GoValidationSpec{Race: true},
	},
	AdditionalChecks: func(ctx context.Context, candidate releasekit.Candidate) error {
		return runProjectChecks(ctx, candidate.RepositoryDir)
	},
})
if err != nil {
	return err
}
fmt.Println(result.Version, result.Commit)

The repository must have a clean index and worktree on main, and the selected version must be stable vMAJOR.MINOR.PATCH. The committed docs/releases/<version>.md note must have a first Markdown H1 containing the product name and exact version as complete title elements. No local tag with that version may already exist.

ReleaseKit runs one go test -mod=readonly -count=1 ./... suite with the available compatible local Go toolchain, then calls AdditionalChecks once when supplied. Set Validation.Go.Race to run that suite with -race; the zero value keeps the ordinary native suite. ReleaseKit does not download a different toolchain automatically. If the race prerequisite is unavailable, the go-test check fails rather than being skipped. The suite uses the Go host target, disables workspace and module network access, and ignores ambient GOFLAGS, experiment, and CPU feature overrides. Effective cache and native cgo/C-tool settings are preserved, including values from Go's persistent environment file. The check revalidates the branch, commit, and cleanliness after validation.

A successful check is evidence about the local candidate only. It does not check whether a remote branch or tag is available and does not create a tag. The check command reads the product and optional additional commands from releasekit.json.

Publishing the source tag

releasekit.Publish uses the same request and validation order: the standard suite runs first, followed by AdditionalChecks when supplied. It then performs authoritative remote checks, annotated-tag creation, and an exact tag push. The selected remote must publish main at the captured commit and must not already contain the selected version tag. A successful result includes the endpoint and tag object ID. Publication states distinguish an unattempted push, a tag that was created locally but not pushed, a successful push, a guard conflict, and an unresolved push error. See the publication guide for the complete workflow.

When a push reports an error, ReleaseKit makes one bounded query for the authoritative tag. An exact tag object match confirms success. An absent tag is reported as not_published, a different object as conflict, and an unreadable query as unknown. The local annotated tag is retained in every case; an unknown result is neither success nor proof that the remote lacks the tag.