// Releases

Create a release

Snapshot package versions and the current deployment plan into a new release.

POST/api/release

Description

Creates a new release for a project. A release locks in the project's deployment plan (steps), the chosen package versions, and the project channel - everything needed to redeploy the same thing later.

If version is omitted, the server proposes the next version using the project's release versioning rules. If packageVersions is omitted, the latest version of every project package is selected by default.

If channelName is omitted the project's default channel is used (unless ignoreDefaultChannel = true).

Channel version rules

If the resolved channel has version rules, they are enforced here, and they shape the defaults:

  • The proposed version respects the channel. When version is omitted the proposal is seeded from the releases already in that channel - so a stable and a prerelease stream keep independent numbering - then snapped up to the minimum of the channel's version range and given the channel's default prerelease tag.
  • Default package versions respect the channel. For any package not named in packageVersions, the newest version the channel allows is pinned, rather than the newest version that exists.
  • Explicit values are validated, never silently corrected. A version or a pinned package version the channel disallows fails the request with a message naming the channel and the reason.

The channel and its rules are always loaded server-side from the channel resolved for this request, so a caller cannot influence which rules apply.

Parameters

NameInTypeRequiredDescription
projectId body string yes ID of the project to create the release for.
channelName body string no Channel name to bind the release to. Defaults to the project's default channel. The channel's version rules are enforced on this request.
ignoreDefaultChannel body boolean no Set to true to skip the project's default channel when channelName is omitted. The release is then created without a channel, and no channel rules apply.
version body string no Explicit SemVer version. Defaults to the next proposed version for the resolved channel. Must satisfy the channel's release version rule.
notes body string no Free-form release notes.
packageVersions body object no Map of packageId -> version to pin specific package versions. Each pinned version must satisfy whichever channel package rule governs that package. Packages left out default to the newest version the channel allows.

Errors

StatusMeaning
400 Invalid projectId, invalid channelName, or pinned packages with versions that don't exist.
400 version is not allowed in the resolved channel - the message names the channel and whether the version range or the prerelease tag rejected it.
400 One or more pinned package versions are not allowed in the resolved channel - the message lists each rejected packageId @ version with the reason.
400 No available version of a project package satisfies the channel's rules, so there is nothing to pin for it. Push a compliant package version, or create the release in a different channel.
401 Missing or invalid Basic auth credentials, or the service account lacks the required role.
400 Validation failed - the response includes errorcode = InvalidParameter and (where applicable) a validationErrors map.