# 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. |
| `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.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.module_distribution.workspace_files` is true, it reports
committed blob entries whose basename is `go.work` or `go.work.sum`, including
nested paths and symlinks. It checks candidate distribution contents regardless
of `GOWORK`; it does not select or change the workspace used by Go commands,
and it does not alter existing vendor behavior. Omitted or false disables it.
When `validation.module_distribution.local_replacements` is true, it parses all
committed `go.mod` declarations, including vendor and nested modules, and 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,
    "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 repository-relative file or
directory paths. 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.
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](cli.md) for the invocation and exit statuses.

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.