200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 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.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:
|
|
|
|
```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` 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.
|
|
|
|
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.
|