ReleaseKit/docs/config.md

Configuration

ReleaseKit reads a JSON profile from <repository-root>/releasekit.json by default. The repository argument defaults to the current directory; the CLI resolves its containing Git checkout root. A relative profile path is resolved from that root; 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 with its own go.mod; 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.

module_dir names the selected module's physical location in the repository; ReleaseKit reads its declared import path from that module's own go.mod. The physical directory and declared path are distinct: a declared /v2 module can live either at integrations/core or integrations/core/v2, while both use the same full release tag. Root-only profiles can omit module_dir and do not need a module map.

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 COPYRIGHT, LICENSE, and docs/oss/attribution.md when present for enabled file checks; [] selects no shared files. An explicit list replaces those defaults. Each explicit file must exist in the candidate, even when no file checks are enabled. Paths are literal, repository-relative files with no glob semantics and may select a file outside the chosen module. ReleaseKit deduplicates them with module inputs by path. This field does not enable any checks or expand Go test, vet, or package-compilation scope. Automatic file inputs stop at independent nested-module boundaries; vendored files remain included. Reference inspection can read destinations elsewhere in the captured repository without adding them to those inputs. 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 uses the selected file inputs, including vendor and explicit shared files, and 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; an explicit shared-file selection can include an individual declaration from another module. 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 takes a full Git TAG; its final path component is the stable semantic version and the complete value is checked against the profile's derived tag. By default it fetches the selected tag, confirms its peeled commit matches the provider-supplied commit ID, checks it out detached, and verifies the tag, HEAD, and clean worktree. With --prepared, it performs the same checks against an existing checkout without fetching or checking out. It then loads the profile from that source and validates delivery settings and credentials. An optional --expected-module checks a launcher's module selection against the profile. It runs go mod download only when the profile has selected build targets; source-only delivery does not need application dependencies. Default preparation may access the network and may update go.sum. For binary tagged delivery, prepare and commit that module's sums before tagging so dependency preparation leaves the tagged checkout clean. 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.