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, FullVet: 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. Set Validation.Go.Race to run that suite with -race; set Validation.Go.FullVet to run go vet -mod=readonly ./... after successful tests, with test-time vet disabled for the suite. It calls AdditionalChecks once after shared validation when supplied. Their zero values retain the ordinary native test behavior. ReleaseKit does not download a different toolchain automatically. If race prerequisites are unavailable, the go-test check fails rather than being skipped; a selected full-vet failure is reported as go-vet. 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.