Configuration reference

Publication uses committed TOML and package metadata. Source commits, output locations and attempt identities are invocation inputs, not persistent policy.

Workspace publication configuration

The default file is .cargo/release_plan.toml relative to the selected Cargo workspace. Relative --config overrides resolve from that workspace, not the shell’s invocation directory. Absolute overrides are also accepted. Publication requires tracked configuration inside the source repository; it need not be inside a nested Cargo workspace.

This is a complete example of the configuration format:

schema-version = 1
repository = "example/widgets"
release-branch = "main"
targets = [
    "x86_64-unknown-linux-gnu",
    "aarch64-unknown-linux-gnu",
    "x86_64-pc-windows-msvc",
    "aarch64-pc-windows-msvc",
    "aarch64-apple-darwin",
]

Replace the example repository and release branch; no particular release-branch name is required.

For a library-only workspace, an empty targets = [] is valid. For a binary package, the effective target set must be nonempty.

The supported native target set is:

The action revision selects matching native runners. Intel macOS is not in this support set.

check --config validates configuration and binary publication inputs offline. Ordinary check without that option retains its version-readiness scope. Publication reads configuration by default. None of these settings silently changes the history default for version assessment; automation supplies --release-history and any --merge-target explicitly.

Package metadata

These entries are optional:

[package.metadata.release-plan]
private-api = true
release-targets = ["x86_64-pc-windows-msvc", "aarch64-pc-windows-msvc"]

private-api declares that a library does not offer an independently supported consumer API. It defaults to public when absent; binary-only packages have no library contract to compare. The declaration does not disable publication or dependency propagation.

Checker capability is separate. Procedural-macro libraries can offer a supported consumer API without declaring it private. Their Cargo target metadata excludes them from direct checker invocation and records the unsupported comparison explicitly. They remain subject to semantic assessment, release planning and publication. A private implementation’s re-exported items are assessed through the public package; the private declaration does not make that exposed contract private.

A CLI package with an internal library target must also declare private-api = true when it offers no supported Rust library API. This does not waive compatibility requirements for its command line or documented artifact formats.

release-targets narrows the workspace’s binary target selection. Omit it for the whole workspace selection. Invalid targets or an empty effective binary selection are errors.

Cargo’s publish = false is different: it excludes the package from publication while retaining tracked version-group alignment.

Version groups come from exact local workspace dependencies, not metadata. The obsolete [workspace.metadata.release-plan.groups] table is not accepted.

External types

[package.metadata.cargo_check_external_types]
allowed_external_types = [
    "widget_impl::*",
    "other_library::PublicType",
]

Entries describe defining crate paths, including re-exported types. Verify them with cargo-check-external-types for supported features and platforms. An absent list allows no external exposure. See the adoption prerequisite.

Binary metadata and naming

Each publishable binary package declares one executable that builds with Cargo’s default features. Authors are responsible for checking that build selection. The offline metadata check validates binary selection and archive declarations, not feature eligibility or buildability; Cargo checks those during the native build. Its Cargo repository is exactly https://github.com/<owner>/<repository> using the configured destination, without a trailing slash or .git suffix, and its binstall metadata describes the standard ZIP layout:

[package]
repository = "https://github.com/example/widgets"

[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/{ name }-v{ version }/{ name }-v{ version }-{ target }.zip"
bin-dir = "{ bin }{ binary-ext }"
pkg-fmt = "zip"

The brace expressions are literal cargo-binstall template syntax, not placeholders to replace manually.

The sidecar does not append .sha256 to the ZIP filename. Package and executable names can differ. Unix ZIP members retain executable permissions. Both assets must be uploaded for the pair to be complete.

Publication does not silently enable additional features to reach a gated binary, accept arbitrary Cargo build arguments or cross-compile an archive.