ReleaseKit/docs/config.md

Configuration

ReleaseKit reads a JSON profile from <repository>/releasekit.json by default. The repository directory defaults to the current directory. A relative profile path is resolved from that repository directory; an absolute path is used as-is.

The current profile fields are:

Field	Required	Behavior
product	Yes	Product name used by release operations.
module_dir	No	Repository-relative physical Go module directory; omission selects . (the repository root).
remote	No	Selected Git remote; defaults to origin.
expected_push_url	No	Exact effective push URL required by publish; ignored by local check.
checks	No	Ordered additional child commands, each with an argument vector and optional environment map.
validation	No	Optional shared checks selected by ReleaseKit.
build	No	Optional main package, binary name, and selected GOOS/GOARCH target strings.
delivery	No	Optional Gitea base_url, owner, repository, and token_env settings for tagged-source delivery.

Each check requires a nonempty args array whose first element names the executable. Arguments are passed directly to the child process; ReleaseKit does not parse a shell command string. Select a shell explicitly when a check needs shell syntax. Each env map overlays the current environment for that child. The overlay does not modify the ReleaseKit process environment.

Unknown fields are rejected so a setting cannot be silently ignored. The build object contains main_package, binary_name, and targets. A selected target requires the package and binary name; each target is written as one GOOS/GOARCH pair. An omitted or empty target list means no binary work.

The optional validation object selects shared checks implemented by ReleaseKit. validation.shared_files is a committed file list resolved from the repository root. Omission or null uses the optional defaults for enabled file checks; [] selects no shared files. Each explicit file must exist in the candidate, even when no file checks are enabled. Paths are literal and have no glob semantics. This field does not enable any checks. validation.go.race enables the race detector for the single standard Go test suite. validation.go.full_vet runs a separate native go vet pass after that suite succeeds; ReleaseKit disables test-time vet for that suite to avoid running vet twice. validation.go.compile_targets is an ordered array of GOOS/GOARCH pairs. After tests and selected full vet pass, ReleaseKit compiles all packages for each target with cgo disabled. Each pair must include both components; the selected Go toolchain reports unsupported complete targets. This source compatibility check does not name or produce binaries, run a target executable, or create an artifact manifest. Omitted or empty compile_targets selects no package-compilation pass. When full_vet is omitted or false, the test command keeps its existing vet behavior. These settings are independent. validation.go_format checks regular committed Go blobs with the Go formatter used to build ReleaseKit. It includes vendor and nested-module source, ignores symlink blobs and the worktree, and reports every selected path whose bytes change under formatting. It never writes formatted bytes back. Omitted or false disables the check. It runs after tests, selected full vet, and selected package compilation, before configured product checks.

When validation.markdown is an object, ReleaseKit checks local destinations and supported heading fragments in committed regular Markdown files. Omission or null disables the check; {} enables it. Schemed and protocol-relative links are skipped, URI query components do not affect path checks, and other existing files or directories receive existence checks only. Missing local destinations, symlink cycles, and missing Markdown headings fail with the markdown-links identity. Outside-checkout destinations are reported as out of scope by default. Set validation.markdown.enforce_checkout_boundary to true to fail those links; submodule contents remain out of scope under either setting.

The parser recognizes inline links, images, reference links, and CommonMark autolinks; link-like text in code is ignored, and raw HTML destinations are outside this check. For linked images, the image source and enclosing link target are checked. Image labels supply alternative text. Relative paths resolve from the source document in the captured commit. Query components are ignored for file existence, and percent escapes in local paths and fragments are decoded once. Fragments are compared in lowercase with anchors derived from visible ATX or Setext heading text. Anchors keep Unicode letters and numbers, underscores, and hyphens; spaces become hyphens, and repeated headings receive numeric suffixes.

When validation.module_distribution.workspace_files is true, it reports committed go.work and go.work.sum files in the selected module inputs, including nested paths and symlinks. It checks the captured candidate regardless of GOWORK; it does not select or change the workspace used by Go commands, and vendored contents remain in scope. Omitted or false disables it. When validation.module_distribution.local_replacements is true, it parses the selected module's committed go.mod declarations. Vendored contents remain in scope, while independently released nested modules are excluded. It reports replace directives whose replacement has no version. These filesystem replacements include relative and absolute paths; versioned module replacements are permitted. Committed go.mod symlinks are resolved within the candidate, and unavailable selected contents or parse failures are reported as inspection errors. This selection is independent of workspace_files and Go's GOWORK setting. Omitted or false disables it. For example:

{
  "product": "Example",
  "validation": {
    "go": {
      "race": true,
      "full_vet": true,
      "compile_targets": ["linux/amd64", "linux/arm64"]
    },
    "go_format": true,
    "markdown": {},
    "module_distribution": {
      "workspace_files": true,
      "local_replacements": true
    }
  }
}

When validation.file_size is an object, ReleaseKit compares each committed blob's size with limit_bytes. The limit uses decimal bytes and rejects only sizes strictly greater than the limit. An omitted or null object disables the check; {} enables it with a default of 1,000,000 bytes. A missing or null limit_bytes selects that default, zero is a valid limit, and negative limits are invalid.

validation.file_size.exclusions contains literal paths relative to the selected module. Directory exclusions include committed descendants, using path boundaries (assets does not exclude assets-old). Ordinary relative path normalization applies; metacharacters are literal and unmatched paths have no effect. The check measures regular and symlink blobs, including small binaries; symlink size is the committed link text. Gitlinks have no measured size. Only the captured candidate is checked, one offending file is reported at a time, and historical or aggregate repository size is not measured.

The delivery object contains base_url, owner, repository, and optional token_env. Its values are required when running deliver, but credentials are not required for check, publish, or build. token_env names the environment variable containing the Gitea token; it defaults to RELEASEKIT_GITEA_TOKEN. The CLI reads this variable only for deliver and passes its value explicitly to the library operation.

expected_push_url, when nonempty, is compared exactly with Git's resolved effective push URL during publish, before candidate validation. It applies to the push destination when fetch and push URLs differ, and Git URL rewrites such as insteadOf are resolved before comparison. A mismatch fails preflight; omitting the field keeps the selected remote's existing behavior. check is local-only and ignores this publication expectation.

The check and publish commands run one go test -mod=readonly -count=1 ./... suite with Go module and toolchain network access disabled, adding -race when validation.go.race is true. When validation.go.full_vet is true, they add -vet=off to that test command and run native go vet -mod=readonly ./... after successful tests. They then run go build -mod=readonly -o <os.DevNull> ./... in static mode for each validation.go.compile_targets entry, in profile order. Compile failures use the package-compile identity and include the selected target. When selected, validation.go_format checks regular committed Go source with go/format after package compilation; unformatted paths use the go-format identity. When validation.module_distribution.workspace_files is true, shared validation also reports committed go.work and go.work.sum blobs after Go formatting, using the workspace-files identity. Uncommitted workspace files are not inspected. When validation.module_distribution.local_replacements is true, shared validation parses committed go.mod files after workspace inspection and reports filesystem replacements as local-replacements, with path, directive line, and target. Versioned replacements are permitted; parse and inspection failures preserve their causes. When validation.file_size is selected, shared validation checks committed blob sizes after module-distribution checks and reports the first oversized path with the file-size identity and measured and limit byte counts. When validation.markdown is selected, Markdown checking follows file-size inspection and runs before configured product checks. Out-of-scope observations are written to the command's standard error and do not fail validation unless the checkout boundary is enforced. Submodule observations remain nonfailures. Configured checks commands run afterward, once each in order, as additional product checks. Artifact builds selected by the separate build setting run after shared validation and product checks.

Do not repeat the standard suite or vet in checks; doing so repeats work. The build command uses the selected build settings and writes binaries to dist unless --output selects another path. The deliver command uses the delivery destination and token. By default it passes selected targets to the delivery facade, which builds tagged-source artifacts into temporary storage and removes them when delivery returns. An absent build object or an empty target set selects page-only delivery. Use build --output DIR followed by deliver --assets DIR when artifacts must be retained for retries or when build and delivery credentials need separate invocations. Ordinary deliver does not download application dependencies or change the checkout.

ci-deliver uses the same profile after preparing the selected tag in the checkout. It checks out the tag only after its peeled commit matches the provider-supplied commit ID, then loads the profile and validates delivery settings and credentials. It runs go mod download only when the profile has selected build targets; source-only delivery does not need application dependencies. This preparation may access the network and may update go.sum. The command takes CI values as arguments, so profile settings remain independent of Woodpecker environment variable names. See the CLI contract for the invocation and exit statuses.

This application dependency preparation is separate from bootstrapping the ReleaseKit executable. The maintained module-based tag workflow verifies the tag first, then uses temporary copies of that tag's module files to build the ReleaseKit version selected by the consumer's go.mod. The delivery guide describes that bootstrap, the self-bootstrapped source workflow, and the separately installed tool option.

ReleaseKit's source-only profile is releasekit.json. See the source-only profile and binary profile. The CLI contract lists the currently available command.