Content Releases user guide

Learn to use Content Releases to organize and schedule updates across multiple documents.

Content Releases lets you organize and schedule updates across multiple documents. You can plan, preview, and validate significant changes in advance, then publish them together.

Content Releases provide several key benefits:

• Coordinate updates: Simultaneously manage and publish updates across multiple pages and channels, ensuring consistency.
• Reduce manual effort and risk: Automate scheduling to minimize manual tracking and prevent errors or conflicting changes.
• Gain confidence with previews and validation: Preview and validate scheduled releases to guarantee readiness before going live.

For developer documentation on how to configure, integrate, and interact with Content Releases programmatically, go here:

Content Releases requires Sanity Studio v3.77.0 or later, where it is enabled by default. Official plugins, such as AI Assist, the Vision Tool, and presentation-related plugins, also need to be up to date. If you're experiencing issues using Content Releases, check with your administrator and direct them to the Studio configuration.

Content Releases introduces the concept of a release. Releases are a way to group multiple document changes together into a single unit that can be previewed, validated, scheduled, and published as one.

The most basic workflow is as follows:

• Create a release.
• Add documents to a release to create new document versions.
• Make changes to the documents.
• Publish the release.

When you create a release, you must choose a release type. There are three available types:

• As soon as possible (ASAP): You plan for these changes to go live as soon as they're ready. They'll have a prominent Run release action available on the release details screen.
• At time: You have a planned date and time in mind. You'll be able to schedule these for a specific time from the release details screen.
• Undecided: You're unsure, or don't want to set a type. These will also hide the publish and schedule actions behind the release's More options menu to prevent accidental publishes.

The type dictates the order a release shows up in Studio to reflect when it will publish compared to other releases, but you can change the type at any time from the release detail screen.

When you're working on a release, the document screen displays details about versions of the document. Document version names correspond to release names. Published and drafts are always enabled, but additional versions are displayed as documents are added to releases.

Much like each published document can only have one draft, each release can only contain one version of a document.

Select a version name to switch between versions. Right-click the name to reveal a menu with options, including: copy versions between releases, or discard a version.

The releases screen displays any upcoming releases. Bold dates in the calendar indicate releases with date estimates. You can also see the number of changes in each release, and warnings if there are validation errors.

The global perspective is your view into the state of all documents relative to the selected release. By selecting a release, you're viewing not only its changes, but all changes in published documents and to-be-published documents. You can hide individual releases from view, if they are higher in the list than your selected release, or view just the Published perspective.

You can work directly on a draft and publish it without creating a release. You can also work on a draft, then copy it to a release.

One important thing to keep in mind. Publishing a release will not reset a draft. If you created a draft and made changes, then copied it to a release, that draft still exists. When you run a release, the confirmation dialog offers an Update existing drafts option. Selecting it discards the existing drafts of documents in the release so drafts match what was published. Unpublished draft changes are lost. There are two ways you can keep these leftover drafts in check:

• If you know you're working on a release, start the changes in the release. This way a draft document is never created.
• After copying a draft to a release, return to the draft document and discard the draft version.

Content Releases is designed to work with most workflows, but you may experience issues with exceptionally large documents and releases.

• A single release can contain a maximum of 1,000 documents.
• The total size of all of your JSON documents combined in a release cannot exceed 100 MB. This is the size of the document's JSON data itself, not linked assets like images or files.
• Releases publish documents in batches based on size and reference connections. For larger releases, there may be small delays when individual documents go live. To avoid this, smaller releases of dependent documents can help ensure they release at the same time.
• Releases are published one at a time and are ordered by the time they will be published. If releases will be published at the same time, their order will be chosen at random.
• If a release is blocked by another release, it waits up to 10 minutes before the release is marked as failed. If multiple large releases are scheduled for the same time, consider staggering their release times.

To add new documents and changes to a release, you first need to create a release.

• Locate the calendar icon in the top right corner of the toolbar.
• Select the down arrow icon to reveal a list of releases.
• Select New release to create a new release.
  • Select an approximate time of release.
  • Enter a release title (optional).
  • Enter a description for the release (optional).
  • Select Create release.

You can change these values later by navigating to the release on the Releases screen.

When a document is part of a release, it's no longer connected to changes in drafts or the published document. It's like a snapshot in time that has its own future. Keep this in mind when interacting with different versions of the same document.

There are multiple ways to add a document to an existing release.

• Navigate to the Releases screen by selecting the calendar icon in the top right of Studio.
• Select the release name to navigate to its detail screen.
• At the bottom of the list of documents, select Add document.
• Search for and select a document.

• Ensure you are in a release perspective by pinning a release. You'll know you've pinned a release if the release name is next to the calendar icon in the toolbar.
• In a document's editor view, select the Add to release button in the top bar. This button and bar should match the color scheme associated with the release perspective.

Alternatively, you can right-click a release label at the top of a document and select Copy version to to copy the selected document version to a release.

Once a document is part of a release, you'll be able to edit the release version by ensuring the release is selected at the top of the document.

Removing a document from a release discards any changes unique to that version. This action won't remove the document from other releases.

There are three ways to remove a document from a release.

• Select the release name to navigate to its details screen.
• Identify the document you want to remove and select the "..." icon to reveal additional options.
• Select Discard version and confirm the selection when prompted.

• Confirm you are in the perspective for the desired release. You should see the release name next to the calendar icon in the toolbar, as well as the highlighted release name at the top of the document.
• At the bottom right of the document screen, select the "..." icon.
• Select Discard version and confirm the selection when prompted.

• On the document header, find the chip with the version you want to discard.
• Right-click the chip to open the context menu.
• Select Discard version and confirm the selection when prompted.

You can copy a document version to a different release from the document view.

• Navigate to the document you want to copy.
• Right-click the release name you want to copy from.
• Hover over Copy version to.
• In the popover menu, select the destination release.

Sometimes you want a release to unpublish, or remove a live document. This converts a published document back to a draft once the release is published.

• Add the document to a release.
• In the bottom right corner of the document screen, select the "..." icon.
• Select Unpublish when releasing and confirm the selection when prompted.

When unpublishing a document, the contents of the published document are used to create a new draft document associated with the published ID.

If a draft document with the same published ID as the version document already exists, it will remain and the unpublished contents will be lost.

All strong references will be converted to weak references on unpublish. If the draft document is subsequently re-published, those references will be converted back to strong references.

To discard a document version, follow the steps listed in Remove a document from a release.

To discard changes from the Draft version, select the More options at the bottom right of the document screen and select Discard changes.

After creating a release, you can choose to publish it on demand or schedule a publish.

• Navigate to the release screen for the release you want to publish.
• Select Run release and confirm. For At time and Undecided releases, this action is in the release's More options menu rather than the primary button.

To schedule a release, first set a release time and date. You can do this when creating a release, or by selecting the release time label and selecting At time from the release screen. You can adjust this time later if needed.

Next, select Schedule release in the bottom left of the release screen.

Confirm the release time and date, then select Yes, schedule.

While a release is scheduled, its version documents are locked. Select Unschedule release before editing a document in the release or adding another one.

To unschedule a release, select the Unschedule release button in the bottom right of the release screen.

The Archived tab lists both archived releases and releases that have already published. Archiving is a separate action you can take on a release that hasn't published yet, to take it out of the active list while preserving it for reference.

There are two ways to manually archive a release.

• Select the "..." icon for the release you want to archive.
• Select Archive release.

• In the bottom right, next to the Publish / Schedule button, select the "..." icon.
• Select Archive release.

You may unarchive an archived, unpublished release. Published releases cannot be unarchived.

There are two ways to manually unarchive a release.

• Select the "..." icon for the release you want to unarchive.
• Select Unarchive release.

• In the bottom right select the "..." icon.
• Select Unarchive release.

Release order is determined by when the release will be live, with exceptions for ASAP and Undecided. This is the release type.

• ASAP releases come first, in order of creation.
• Dated releases come next, ordered by date.
• Undecided releases come last, ordered by creation.

To change the order of a release, change the date and time associated with it.

Pinning a release sets the global perspective in Studio. This is indicated by the color change in the toolbar, as well as the highlighted release name throughout Studio.

You can only pin one release at a time.

There are three ways to pin a release.

• In the top toolbar, select the dropdown arrow next to the calendar icon. If a release is currently pinned, the arrow will display next to the pinned release.
• Select the release name for the release.

• Locate the release to pin.
• Select the pin icon to the left of the release name.

• Navigate to the release you want to pin.
• Select the pin icon on the top left, above the release name.

You can view past releases, including unpublished ones, from the Archived tab on the main releases screen. Published and archived releases are retained for a limited period based on your plan's retention window, after which they're automatically removed.

You can edit the name, estimated release time, or description directly on the release screen.

To change the title or description, select the field and begin typing.

To change the estimated publish time, select the release time label and choose a new time.

When viewing a future release, you can choose to hide earlier releases from the global perspective view. This lets you hide document changes made by specific releases, while still previewing a subset of changes across releases.

• To hide versions from a specific release, first set your global perspective.
• In the release dropdown view, select the open eye icon next to any release you want to hide.
• To reveal a hidden release, select the closed eye icon.

If your team has enabled Presentation, you can preview a release by pinning it and then selecting the Presentation Tool in Studio. You'll know it's been pinned if the name displays alongside the calendar icon instead of Drafts.

Keep the release layering concept in mind, and use the hide release feature to customize your preview perspective.

You can return to the state prior to when a release was published by reverting the release. When reverting, you can either revert the release immediately or create a new release, which you can then review and schedule.

• Navigate to the releases screen by selecting the Calendar icon from the perspective picker in the top bar.
• Select Archived to view published and archived releases.
• Select the release you want to revert to navigate to the release.
• In the lower right, select the Revert release button.

When you revert a release, any new documents that didn't exist outside of the release will be reverted to drafts in your dataset.

You can build off of an existing release by duplicating it. This is useful in scenarios where you want to work beyond a current release, but want any scheduled changes to carry over. There are two ways to duplicate a release.

• Select the "..." icon for the release you want to duplicate. You can duplicate an active or scheduled release. Duplicate release isn't available for releases that have already published or been archived.
• Select Duplicate release.

• In the bottom right, next to the Publish / Schedule button, select the "..." icon.
• Select Duplicate release.

Release layering is the concept of displaying documents based on where a release falls in the release timeline and which perspective is active.

This allows editors to preview document changes across multiple releases. You can see a simplified version of this in how drafts override published documents in Presentation.

In Studio, release layering works on a timeline. The type and time of release indicates where a release falls on the timeline. You already know published and draft, but there are also as soon as possible (ASAP), timed, and undecided.

The layer follows this order, starting at 1 and adding changes.

• Published
• Draft
• As soon as possible (ASAP)
• Timed (A planned time in the future)
• Undecided

When viewing a release with an undecided release time, you will see all changes in other documents from drafts, ASAP releases, and timed releases stacked atop published documents—plus any changes on the undecided release(s). These views of your content in Studio are the global perspective.