---
title: "Create a Release"
method: POST
path: "/releases/create/v1"
tags: ["Releases"]
---

# Create a Release

`POST /releases/create/v1`

## Request body

- CreateReleaseCommandV1
  - `ChannelName` string — Name of the channel to use for the new release. Omit this argument to automatically select the best channel.
  - `CustomFields` object — Values for the project's custom release fields, if it defines any, keyed by field name.
  - `GitCommit` string — Only set alongside GitRef, when a specific commit is needed; GitRef alone uses the tip of that ref.
  - `GitRef` string — The Git branch, tag or commit to snapshot the deployment process from. Required for a project that stores its configuration in Git, and must be left unset for one stored in the database — the command fails either way round. List a project's branches with get_branches.
  - `GitResources` string[] — Git ref to use for a git resource in the release. Format: StepName:GitRef or StepName:GitResourceName:GitRef. If the GitResourceName is omitted, it's assumed to be the primary git resource for the step. The GitRef can be replaced with an asterisk. An asterisk will use the tip ref of the step-defined default branch.
  - `IgnoreChannelRules` boolean — Create the release even when a package version, or the Git reference, violates the channel's version rules. This overrides a deliberate guardrail, so prefer correcting the versions or letting Octopus select the channel; only set it when explicitly asked to.
  - `IgnoreIfAlreadyExists` boolean — If a release with the same version number already exists, return that one instead of failing — so the returned ReleaseId may be an existing release rather than a newly created one.
  - `PackagePrerelease` string — Restrict automatic version selection to pre-release versions carrying this tag, for example "beta". Ignored for steps whose version is pinned by PackageVersion or Packages.
  - `Packages` string[] — Version number to use for a package in the release. Format: StepName:Version or PackageID:Version or StepName:PackageName:Version. StepName, PackageID, and PackageName can be replaced with an asterisk. An asterisk will be assumed for StepName, PackageID, or PackageName if they are omitted.
  - `PackageVersion` string — One version to use for every package step. Leave unset to take the latest version of each package; use Packages instead to pin versions per step.
  - `ProjectName` string, required
  - `ReleaseNotes` string — Release Notes for the new release. Styling with Markdown is supported.
  - `ReleaseVersion` string — Leave unset to let Octopus pick the next version from the project's versioning strategy, which is usually what you want.
  - `SpaceId` string, required
  - `SpaceIdOrName` string, required — Both this and SpaceId are required, and normally hold the same space ID; set both.

## Response `201`

Created

- CreateReleaseResponseV1
  - `ReleaseId` string, required
  - `ReleaseVersion` string, required

## Other responses

- `400` — Bad request. Either the payload was not structurally valid or business rules did not permit the operation.
- `404` — Not found. One or more of the entities involved in the operation was not found.

---

[API](https://skmtc.net/octopus/apis/octopus-server-api.md) · [All operations](https://skmtc.net/octopus/apis/octopus-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octopus/octopus-server-api/revisions/b296c3a60aa5/schema)