Guides · Publishing
Releases
Gather changes to several entries into a release and put them live together, now or at a set time. Adding entries, what publishing a release checks, scheduling, review, webhooks and the agent API.
A launch is rarely one entry: a landing page, three product pages, the navigation that links to them and a banner that comes down, all at the same moment. A release gathers those changes in one environment and puts them live together, now or at a set time. Either every entry in it goes live (or comes down), or nothing changes.
Releases in the sidebar lists an environment's releases, open and published. New release makes one, with a name and an optional description. Releases belong to one environment, like the rest of its content, and promoting doesn't copy them.
Adding entries
On an entry's page, Add to release… in the status card beside the form adds the entry: pick a release, or A new release… with a name, and choose under In the release whether it is published or unpublished with it. The release takes the draft as it is now, so save first if you have changes. The status card then says In or Comes down with and the release's name.
- An entry is in a release once, but can be in several releases.
- Only a published entry can be unpublished with a release. Folders can't be in one.
- A shared block that is live on pages asks which of them to leave as they are, as publishing it does; the release keeps that choice.
- A release holds up to 500 entries.
A release's page lists its entries, each with what happens to it and its state:
- Ready.
- Changed since added: the draft was saved after it was added. Take the latest draft updates the item.
- Deleted: the entry is in the trash. Take it out to publish the release; restoring the entry from the trash brings it back.
Take out removes an entry from the release; its draft stays as it is.
What goes live
Publish release checks every entry exactly as publishing or unpublishing it alone would (required fields, references, unique values, the improve block), with one difference: entries in the release count as published for each other's references. Drafts that link to each other go live together, and an entry the release unpublishes counts as gone, so published content is never left pointing at it. If anything is refused, nothing changes, and the error names the entries.
Which draft goes live depends on the environment's publishing setting:
- Open: each entry's draft as it is at the moment the release is published, so a typo fixed after adding it goes live too.
- Reviewed: only the revision that was added. A release with an entry changed since is refused until you take its latest draft or take it out, so nothing goes live that wasn't reviewed.
A published release stays on the list, read-only, with who published it and when. A release is published once.
Scheduling
Schedule… sets one time for the whole release, in your local time; empty, or Clear schedule, clears it. Schedules are checked every minute.
- The release is published as the person who scheduled it, with their role at that moment, and goes through exactly the same checks.
- If it is refused, nothing changes: the release stays open and shows The scheduled publish failed with the reason.
- An entry's own schedule and a release are independent: whichever runs first publishes the entry.
Review
Where an environment's publishing is reviewed, only admins publish or schedule a release. Everyone else who edits sees Ask for review, with a note for the reviewer; the release shows when review was asked. An admin then publishes or schedules it, which closes the ask.
Once an admin has scheduled a release there, its entries are the admin's approval: only admins add, update or take out entries until the schedule is cleared, which anyone who edits may do.
Creating releases and adding entries to them is open to everyone who edits content.
Webhooks and activity
Publishing a release sends every entry's own entry.published, block.published or entry.unpublished, as publishing it alone would, so existing receivers keep working. Then one release.published follows, with the release and every entry in it and its action, for a site that rebuilds once per launch. Asking for review sends release.review_requested. See webhooks.
Activity records creating, scheduling, publishing and deleting a release and asking for its review, next to each entry's own publish.
Agents
Under /api/agent/organizations/{org}/spaces/{space}/{environment} in the agent API, and as MCP tools of the same names:
| Request | Tool |
|---|---|
GET releases | listReleases |
POST releases/create | createRelease |
GET releases/{releaseId} | getRelease |
POST releases/{releaseId}/update | updateRelease |
POST releases/{releaseId}/delete | deleteRelease |
POST releases/{releaseId}/entries | addReleaseEntry |
POST releases/{releaseId}/entries/remove | removeReleaseEntry |
POST releases/{releaseId}/publish | publishRelease |
POST releases/{releaseId}/schedule | scheduleRelease |
POST releases/{releaseId}/review | requestReleaseReview |
addReleaseEntry takes entryId, action (publish by default, or unpublish), locales to publish only those languages' values (as publishing an entry can), and for a live shared block exclude, the pages to leave as they are. Adding an entry that is already in the release updates it to its latest draft. The same role checks apply as in the dashboard, production included.
Previewing a release
Preview opens your site at its preview URL as it will be the minute after the release is published: every entry is its published copy, except the ones the release publishes (their current draft, or only the item's locales) and the ones it unpublishes, which are gone. Other drafts are not shown, so you see the launch, not everyone's work in progress.
The button opens the release's first page with a preview token made for that release, so your site reads it like any other preview, drafts included: nothing extra to build. A delivery request can also ask for a release itself with ?release=<releaseId> and a preview token, on pages, entries, redirects and content-model.