# 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`. |
| `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.
For example:

```json
{
  "product": "Example",
  "validation": {"go": {
    "race": true,
    "full_vet": true,
    "compile_targets": ["linux/amd64", "linux/arm64"]
  }}
}
```

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.

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. 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.