ReleaseKit/docs/consumers/publish.md

Source tag publication

Use releasekit.Publish to validate a committed candidate and push its exact annotated source tag:

result, err := releasekit.Publish(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.CandidateCommit, result.TagObject)

Publication captures a clean candidate on main, validates its committed release note, and checks the selected remote before running candidate checks. It 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 that suite. The zero values keep ordinary test-time vet behavior. It then calls AdditionalChecks once when supplied. The standard suite cannot be replaced; move product-specific behavior into AdditionalChecks and remove repeated standard-suite commands from custom checks. A failed suite or additional check prevents tag creation, and wrapped errors preserve their causes. If race prerequisites are unavailable, the selected suite fails as go-test instead of silently running without the race detector. Full-vet failures are reported as go-vet and stop publication before tag creation.

If Build selects targets, ReleaseKit verifies them after the standard suite and additional checks, before creating the tag. The operation then rechecks the candidate and remote guards, creates an annotated tag for the captured commit, and pushes only that tag object.

A successful result means Git confirmed the push or an exact authoritative tag query confirmed it after a push error. The local tag is retained after a failed push. PublicationState distinguishes a known failure, conflict, confirmed publication, and unresolved outcome. Resolve an unknown result against the captured endpoint before retrying; see the maintainer procedure for the recovery steps. The CLI contract documents command output and exit statuses.