# Source tag publication

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

```go
result, err := releasekit.Publish(ctx, releasekit.ReleaseRequest{
	RepositoryDir:   "/work/project",
	ModuleDir:       "integrations/example",
	Product:         "Example",
	Version:         "v1.2.3",
	ExpectedPushURL: "ssh://git.example/owner/example.git",
	Validation: releasekit.ValidationSpec{
		Go: releasekit.GoValidationSpec{Race: true, FullVet: true},
	},
	AdditionalChecks: func(ctx context.Context, candidate releasekit.Candidate) error {
		return runProjectChecks(ctx, candidate.ModuleDir)
	},
})
if err != nil {
	return err
}
fmt.Println(result.ModulePath, result.Version, result.Tag, result.CandidateCommit, result.TagObject)
```

`ModuleDir` is a repository-relative physical module directory; omit it or use
`.` for a root-module release. ReleaseKit reads the selected module's committed
declaration and derives the complete Git tag from its declared module path and
physical location. `Version` remains the stable semantic version. The note is
`<module>/docs/releases/<version>.md`; an on-disk `/v2` directory is part of
the note path but is removed from the tag prefix only when the module path ends
in `/v2`. `PublicationResult` returns the absolute `ModuleDir`, declared
`ModulePath`, complete `Tag`, and existing commit and tag-object evidence.

The optional `ValidationSpec.SharedFiles` selects additional committed files
for enabled file checks. Its nil and empty-slice behavior is described in the
[candidate check guide](check.md#local-candidate-check).

Publication captures a clean candidate on `main`, validates its committed
release note, and checks the selected remote before running candidate checks.
Set `ExpectedPushURL` to require the effective push destination to match an
exact string. Git URL rewrites are resolved first, and the push URL is compared
when fetch and push URLs differ. A mismatch fails preflight before Go validation,
callbacks, or tag creation; detect it with
`errors.Is(err, releasekit.ErrUnexpectedPushURL)`. `Check` ignores this
publication-only field.
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.

Set `Validation.Go.CompileTargets` to compile packages for each complete target
pair after tests and vet. This uses `CGO_ENABLED=0`, produces no artifact, and
does not execute target binaries. A failure is reported as `package-compile`
with the selected target and prevents tag creation.

Set `Validation.GoFormat` to check committed regular Go source using the Go
formatter built into ReleaseKit. It uses the selected file inputs, including
vendor and explicit shared files, and ignores
worktree changes and symlink blobs, and reports unformatted paths as
`go-format` without changing files. The default is disabled. The check follows
tests, selected vet, and package compilation, and a failure stops publication
before product checks or tag creation.

Set `Validation.ModuleDistribution.WorkspaceFiles` to reject committed
`go.work` and `go.work.sum` blobs in the selected inputs, including symlink entries.
The rule reads the captured candidate regardless of `GOWORK`; uncommitted files
are ignored, and Go workspace selection and vendor behavior are unchanged. Its
zero value disables the check. Findings use `workspace-files` and stop
publication before product checks or tag creation.
Set `Validation.ModuleDistribution.LocalReplacements` independently to parse
selected module's committed `go.mod` declarations. Vendored contents remain in
scope; automatic inputs stop at independently released nested modules. Explicit
shared files can include another module's declaration. Filesystem
`replace` directives are reported with their source path, line, and target as
`local-replacements`; versioned replacements are
permitted. Committed module symlinks are resolved within the candidate, and
parse or inspection errors retain their causes. This check is independent of
`GOWORK`; its zero value disables it, and a failure stops publication before
product checks or tag creation.
Set `Validation.FileSize` to check each committed blob against a byte limit.
Nil disables the check; an empty object enables the default of 1,000,000
decimal bytes. `LimitBytes` uses strict greater-than, accepts zero, and rejects
negative values. `Exclusions` contains literal files or directories relative to
the selected module, including committed descendants of excluded directories.
Symlink blob size is its link text; gitlinks are omitted. This check measures only the
captured candidate and reports one oversized file with its measurement as
`file-size`; it stops publication before product checks or tag creation.

Set `Validation.Markdown` to check committed local Markdown destinations and
supported heading fragments during publication. Nil disables the check; an
empty object enables it with outside-checkout links reported as out of scope.
Set `EnforceCheckoutBoundary` to fail those links. Submodule contents remain
out of scope under either setting. Observations use the request's output writer;
failures use `markdown-links` and stop publication before product checks or tag
creation.

ReleaseKit-owned selections replace duplicate generic suite, vet, formatting,
distribution, and Markdown checks in configured product checks. Keep
release-note rules and consumer-specific assertions, such as maintained-example
tests, in `AdditionalChecks` or profile `checks`.

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](../release.md)
for the recovery steps. The [CLI contract](../cli.md) documents command output
and exit statuses.