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",
	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 always runs go test -mod=readonly -count=1 ./... with the available compatible local Go toolchain. 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 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.