Publishing

Publishing at a glance

Editing in the composer saves your draft. Publishing is a deliberate step that creates an immutable snapshot in Staging or Production — the version your websites and apps load through the RuleCMS API and embed tokens.

Widgets and shared collections can each be published. Embedded collections publish only with their parent widget. For how shared vs embedded collections behave on publish, see Collections.

Environments

Every project has environments (at minimum Staging and Production). Publishing is always scoped to one environment:

• Staging — safe place to preview integrations, share with stakeholders, and run QA before go-live.
• Production — what end users see. Requires the appropriate publish permission for your role.

The same widget key can exist in both environments with different published content and independent version histories.

How to publish a widget

1. Open the widget in the composer or widget management page and go to the Publish tab.
2. Confirm staging or production matches the environment you intend.
3. Click Publish Now (or Publish New Version if already published).
4. Optionally add a tag name and description in the confirmation dialog — useful for release notes and audit trails.
5. After success, note the published key and version number shown in the UI. Your consuming apps use the published key with an app token to fetch this snapshot.

The first publish creates version 1.0.0. Each later publish increments the patch version (1.0.1, 1.0.2, …). Your draft widget continues to evolve separately; publishing never overwrites the draft.

Publishing shared collections

Shared collections have their own Publish tab. When you publish a new version of a shared collection, every widget that references it in that environment resolves to the updated content — without republishing each widget.

Version history — unlimited snapshots

RuleCMS keeps a complete, append-only history of every publish. Nothing is deleted when you ship a new version; each publish adds a row to Publish History.

From the Publish tab or the active published widget page, open Publish History to see:

• Version number — semantic patch increment per environment.
• Tag name — optional label you set at publish time (republished versions auto-tag as Republished from version …).
• Last published at — when that snapshot was created.
• View — open a read-only archive of that exact snapshot, including preview and configuration JSON.

The top row is always the currently active published version — what live consumers receive today. Older rows are historical snapshots you can inspect, compare, and (with permission) promote back to active.

Compare versions

Publish History includes Compare to previous links (when your role allows). Each link opens a side-by-side diff between two snapshots:

• The selected historical version vs the version published just before it, or
• The active published version vs a specific history row.

Use compare before republishing or after an incident to see exactly which components, copy, and collection references changed between releases.

Republish a previous version

Made a mistake in production? Need to restore yesterday's layout without manually rebuilding it in the composer? Republish a previous version promotes any historical snapshot to become the new active published version — while keeping the full audit trail intact.

What republish does

• Creates a new version (e.g. active is 1.0.7, you republish 1.0.2 → new active 1.0.8 with 1.0.2's content).
• Makes that new version the active published widget — live apps pick it up after cache refresh.
• Leaves every older history row untouched, including the version you just replaced.
• Auto-tags the new row (e.g. Republished from version 1.0.2).

You are not "going back in time" by deleting history — you are fast-forwarding from an old snapshot. That gives you unlimited rollback attempts without losing the record of what happened in between.

Shared vs embedded collections on republish

How to republish

You can start republish from two places:

1. Publish History — on any row except the newest (active) one, click Publish this version.
2. Version detail page — open View on a historical row, then click Publish this version in the header.

A confirmation dialog explains:

• Which version will become active and what the next version number will be.
• That shared collections are not changed or republished.
• That embedded collections are copied along with the widget.

Click Publish to confirm or Cancel to abort. The same permission that allows normal widget publish (Publish to Staging or Publish to Production) controls republish — no separate permission is required.

When republish is not available

• Already active — the top history row cannot republish onto itself.
• Missing permission — users who can view history but not publish do not see the action.

Republish vs editing the draft

These are independent paths:

• Republish — copies a historical published snapshot forward. Does not change your composer draft.
• Publish Now — copies whatever is in the current draft forward. Does not use history.

After republishing, you can keep editing the draft and publish again whenever ready — the draft always wins on the next normal publish. If you want history to flow the other way — into your draft — use Restore to draft.

Restore a version to your draft

Republish changes what is live. Restore to draft changes what you are editing: it loads any published snapshot back into your composer draft, like checking out an earlier commit into your working directory. From there you edit and publish as usual.

Unlike republish, restore is available for every version in Publish History — including the currently active one. That makes it the fastest way to throw away unpublished draft experiments and get your draft back in sync with what is live.

Why you would use it

• Start over from what is live. Your draft has half-finished changes you no longer want. Restore the active version and the draft matches production again.
• Branch from an older release. Yesterday's layout was closer to the new campaign design than today's. Restore it into the draft, adapt it in the composer, and publish it as the next version — no manual rebuilding.
• Recover lost work. A section was reworked in the draft weeks ago, but the old design shipped in version 1.0.4. Restore 1.0.4 to get the old structure back as editable content.
• Investigate before rolling back. Restore a suspect version to the draft, inspect and fix it in the composer, and publish a corrected forward version — instead of republishing the old snapshot as-is.

What restore does

• Replaces your draft widget's configuration with the selected snapshot. Any unpublished changes in the draft are discarded.
• Does not touch published content. The active published version, version history, and everything your live apps load stay exactly as they are.
• Does not publish anything. After a restore, the snapshot's content lives only in your draft. Ship it with a normal Publish Now whenever you are ready.

Shared vs embedded collections on restore

The embedded collections that were in your draft before the restore are simply no longer referenced by the widget — they are not deleted, but they will not appear in the composer or be published going forward.

How to restore

You can start a restore from two places:

1. Publish History — click Restore to draft on any row, including the newest (active) one.
2. Version detail page — open View on any row, then click Restore to draft in the header.

A confirmation dialog leads with the consequence:

• The current draft will be replaced with that version's contents, and any unpublished draft changes will be lost.
• The published version is not changed.
• Shared collections are referenced as they are; embedded collections are copied into the draft with the version.

Confirm with Restore to Draft or Cancel. On success you get a direct link to open the widget and continue editing.

Restore is controlled by the widget edit permission for the environment — the same permission needed to change the widget in the composer. Publish permission is not required, because nothing is published.

When restore is not available

• Draft widget no longer exists — if the widget the version was published from has been deleted, the restore stops with a clear message.
• Missing permission — users without edit rights for the widget in that environment do not see the action.

Republish, restore, or publish? Quick guide

Consuming published content

Published widgets are fetched by published key and an app token for the target environment. Details are in the API Reference.

When you republish or publish a new version (after the first), RuleCMS invalidates cached copies of that widget for all enabled tokens in the environment so consumers do not serve stale content.

Recommended workflows

Safe production release

1. Publish to Staging; verify preview and dependencies.
2. Run compare against the previous staging version if needed.
3. Publish the same draft to Production with a descriptive tag.

Production incident rollback

1. Open Publish History for the affected widget in Production.
2. View the last known-good version; confirm preview looks correct.
3. Republish that version. Note the new version number in your incident log (history is preserved).
4. For the forward fix, Restore to draft from the known-good version so your draft starts from what is now live, make the correction in the composer, and publish when ready.

Branch a new design from an old release

1. Find the release closest to what you want in Publish History; use View and Compare to confirm.
2. Restore to draft — the old layout, including its embedded collections, becomes your editable draft.
3. Adapt it in the composer, then Publish Now. The result ships as the next version; nothing in history is disturbed.

Discard draft experiments

1. Open Publish History for the widget.
2. Restore to draft on the top (active) row — your draft now matches what users see, and the abandoned experiments are gone from the composer.

Global copy change without touching every page

1. Identify the shared collection used across widgets.
2. Publish a new version of the shared collection only.
3. All referencing widgets pick up the change — no republish required.

Good to know

• Version numbers are per widget per environment — they are not global across your project.
• Tags are optional on normal publish but help your team scan history quickly; republish auto-generates a tag for traceability.
• The version detail page shows an archive warning — you are viewing a snapshot, not necessarily what is live.
• Embedded collections in a version's preview and dependencies tabs reflect that snapshot's copies, which is the most accurate way to audit what republish will restore.
• Restore to draft is intentionally not undoable from the UI — but because published history is append-only, you can always restore again from any version, including the one that was live before you started.