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:

```json
{
  "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](cli.md) 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](consumers/delivery.md#woodpecker-tag-workflows) describes that
bootstrap, the self-bootstrapped source workflow, and the separately installed
tool option.

ReleaseKit's source-only profile is
[releasekit.json](../releasekit.json).
See the [source-only profile](../examples/releasekit.json) and
[binary profile](../examples/releasekit-binary.json). The
[CLI contract](cli.md) lists the currently available command.