releasekit/docs/releases/v0.6.0.md

# ReleaseKit v0.6.0

## Summary

ReleaseKit adds file-based delivery credentials, optional checks for forbidden
committed files, neutral delivery coordination with explicit Gitea selection, and
authenticated, read-only credential preflight. It also corrects dependency
preparation, publication recovery, and build cancellation handling.

## Changes

- Delivery profiles can select a plain token file through `token_file`.
  Relative paths resolve from the checkout root; a nonblank token environment
  value takes precedence. The CLI trims file contents and reports unreadable
  or blank files as credential-loading failures. Library callers continue to
  supply the token explicitly through the destination.
- `ValidationSpec.ForbiddenFiles` and `validation.forbidden_files` select
  literal repository-relative paths that must be absent from the committed
  candidate. This optional check can protect a local token-file path. It
  inspects committed path metadata independently of module/shared-file inputs;
  it does not inspect file contents or history.
- `releasekit.DeliveryRequest.Destination` now uses the facade-owned
  `releasekit.DeliveryDestination`. Set `Forge: releasekit.ForgeGitea` for
  Gitea delivery. The removed `GiteaDestination` type has no compatibility
  alias.
- Delivery profiles must include `"forge": "gitea"`. The selection is
  required only when `deliver` or `ci-deliver` is requested; the URL does not
  infer a backend. `check`, `build`, and source `publish` remain independent of
  delivery selection and credentials.
- `releasekit.PreflightDelivery` allows callers to check a destination without
  a checkout or tag. `Deliver` performs the same read-only preflight
  automatically. For Gitea, the check authenticates through repository-scoped
  reads and makes no test release or asset writes.
- `DeliveryPreflightError` exposes classified failures and retains the
  underlying cause. Successful preflight confirms authentication and repository
  access plus available permission evidence; it does not guarantee future
  release or asset writes. Gitea's code-push permission metadata does not
  establish release-write or asset-write permission.
- The CLI keeps `RELEASEKIT_GITEA_TOKEN` as its default token environment
  setting and preserves configured environment/file precedence. Selection,
  local credential-loading, and classified preflight configuration/access
  errors return status 2; unavailable preflight and cancellation during
  preflight/preparation return status 1. Later authorization failures follow
  delivery outcomes. An unresolved write returns status 3, including when
  cancellation prevents reconciliation; known delivery failures return 1.
- Binary `ci-deliver` checks credentials before application dependency
  downloads and checks again during delivery. The automatic check now precedes
  full local artifact size and digest verification; those checks still finish
  before hosted writes.

## Correctness and efficiency

- Dependency preparation now resolves the containing checkout root, including
  when called from a subdirectory or filesystem alias. `ModuleDir` is relative
  to that root, and empty selection prepares the root module. Standalone use
  retains the supplied directory as its base, including Go-only use when Git
  is unavailable. Damaged checkout metadata and operational discovery failures
  remain errors before dependency downloads.
- Preparation overrides alternate module-file selection from inherited or
  persistent `GOFLAGS`, while retaining other effective Go settings. Downloads
  therefore use the selected module's ordinary metadata.
- Candidate checking rejects a derived release tag that Git cannot create
  before running validation. CI delivery also validates the selected module's
  complete tag before dependency preparation.
- Publication recovery treats a peeled-only tag observation as unresolved,
  retains the original push failure, and reports `PublicationUnknown` with CLI
  status 3. Complete tag observations retain their existing recovery behavior.
- Cancellation and deadline expiration during build source inspection remain
  identifiable through `errors.Is`; partial results retain completed artifacts.
  Local artifact inspection errors also retain their underlying causes through
  delivery.
- Gitea asset operations classify a missing or nonpositive service release ID
  as a malformed observation before making an asset request. Page-only release
  lookup retains its existing minimal response requirements.
- Asset delivery uses linear pending-asset bookkeeping and sorts only missing
  assets once, reducing repeated work during uploads and reconciliation.

## Compatibility

This pre-1.0 minor release changes the public destination type and requires
explicit forge selection for delivery. Gitea is the supported backend.
Preparation callers that previously used a checkout subdirectory as their
implicit module selection must now select that module with `ModuleDir`.
Ambient `GOFLAGS` no longer redirects preparation to an alternate module file.

The module identifier remains `go.maximumdirect.net/releasekit`, and the Go
consumer minimum remains 1.26.0. Receipt schemas and the separate source
publication and hosted-delivery outcomes retain their existing definitions.

## Upgrade guidance

Select v0.6.0 for library and CLI dependencies, then update integrations as
follows:

1. Replace `releasekit.GiteaDestination` with
   `releasekit.DeliveryDestination` and set
   `Forge: releasekit.ForgeGitea` in each API request.
2. Add `"forge": "gitea"` to every profile used for `deliver` or
   `ci-deliver`, including profiles loaded from a tagged CI checkout. Keep the
   existing `base_url`, owner, repository, token environment, and token file
   settings.
3. If handling preflight failures in Go, use `errors.As` to inspect
   `*releasekit.DeliveryPreflightError` and use `errors.Is` or `errors.As` on
   its unwrapped cause as needed.
4. Continue to treat successful preflight as evidence of repository access,
   not a guarantee that a later write will be accepted. Source publication
   continues to use Git authentication and does not require hosted delivery
   credentials.
5. For dependency preparation of a nested module, supply its repository-relative
   path through `DependencyPreparationRequest.ModuleDir`, even when
   `RepositoryDir` already points inside that module. Root-module consumers can
   keep `ModuleDir` empty.
6. To adopt file-based credentials, store the token in an ignored local file
   and configure `delivery.token_file`. Optionally add that same
   repository-relative path to `validation.forbidden_files`. Credential loading
   and candidate file validation are independent selections; configuring the
   file alone does not enable the validator.

See the [delivery guide](../consumers/delivery.md), [configuration reference](../config.md),
[CLI contract](../cli.md), and [Gitea integration guide](../integrations/gitea.md)
for current behavior.

[COPYRIGHT](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.6.0/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.6.0/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.6.0/docs/oss/attribution.md)