Versioning and rollback

How theme deployments are recorded and how to recover by re-uploading a known-good version

Manage theme changes in Basker CMS. Each upload updates the theme document with a new manifest revision and records validation history. There is not a one-click rollback mechanism in the classic theme flow; practical rollback means re-uploading a known-good theme package or testing changes as a separate development theme before replacing the active theme.

Prerequisites:

A theme already uploaded to Basker CMS
CMS admin access or API access with a valid auth token
Familiarity with uploading themes

Steps

1. Understand version tracking

Each theme upload generates a manifestRevision timestamp in ISO 8601 format (e.g. 2025-06-15T14:30:00.000Z). This timestamp uniquely identifies the version. Basker does not use semantic version numbers for themes; the revision timestamp is the version identifier.

The CMS stores additional data per version:

Data	Retention	Description
Manifest revision	Current only	ISO timestamp of the latest upload
Theme manifest	Current only	Templates, blocks, and settings definitions from the latest upload
Validation logs	Last 20 entries	Upload validation results with error/warning counts and uploader identity
Theme ZIP	All versions	Stored in Basker's theme storage, keyed by theme key

Result: You understand what is tracked when a theme version is created.

2. Upload a new version to an existing theme

To update a theme without creating a duplicate, provide both the key and themeId fields in the upload request.

curl -X POST https://your-cms-domain.com/api/themes/add-theme \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@my-theme.zip" \
  -F "tenant=YOUR_TENANT_ID" \
  -F "key=my-theme" \
  -F "themeId=6721a3f5e4b0a1234abc5678"

The key is the theme identifier string (typically the directory name or a UUID assigned on first upload). The themeId is the document ID of the existing theme record.

When both are provided, Basker updates the existing theme document rather than creating a new one. The manifest is replaced with the new upload, and the manifestRevision is set to the current timestamp.

Result: The existing theme is updated. Previous validation logs are preserved (up to the 20-entry limit). The response confirms the update:

{
  "message": "Theme updated successfully!",
  "validation": {
    "errors": 0,
    "warnings": 1
  }
}

3. Review validation history

Each upload appends a validation log entry. The CMS retains the last 20 entries per theme. Each entry includes:

Field	Description
`createdAt`	ISO timestamp of the upload
`theme`	The theme this entry belongs to
`type`	Whether the entry records an `upload` or a `deploy`
`status`	Overall outcome: `ok`, `warning`, or `error`
`errorCount`	Number of validation errors
`warningCount`	Number of validation warnings
`hasCriticalErrors`	Whether the upload contained critical errors
`triggeredBy`	The user who triggered the upload
`triggeredByLabel`	Display name of that user
`manifestDiff`	What changed between the previous and new version
`validationLogKey`	Reference to the full validation report, stored separately and fetched on demand rather than held inline

To view validation history in the CMS admin:

Navigate to Design > Themes.
Click on the theme.
Open the validation log panel.

Result: A chronological list of upload validation results, showing who uploaded each version and what issues were found.

4. Track deployment changes

When a theme that is currently the active theme for a tenant is re-uploaded, Basker automatically creates a deployment log entry. This records:

The tenant and theme involved
Who triggered the upload
A manifest diff comparing the previous and new versions (added, removed, and changed templates, blocks, and settings)

Deployment logs are stored in the theme-deployments collection. They are created only when the re-uploaded theme is the currently selected theme for the tenant.

Result: Deployment logs provide an audit trail of what changed each time the live theme was updated.

5. Test with development themes

To test a new version without affecting the live site:

Upload the theme as a new theme (omit the themeId field) with a different key, such as my-theme-staging.
Preview it using LocalStage by setting the theme ID to the new document.
Verify templates, blocks, and settings render correctly.
When satisfied, re-upload to the production theme using the original key and themeId.

Alternatively, use LocalStage to preview local changes directly without uploading:

localstage theme dev --theme ./my-theme

Result: Changes are validated locally before being deployed to production.

Result

When complete, you will have:

An updated theme with a new manifest revision
Validation history preserved for the last 20 uploads
Deployment logs tracking changes to the active theme
A workflow for testing versions before going live

Verify: In the CMS admin, open the theme and check that the manifestRevision timestamp matches the time of your latest upload. Review the validation log to confirm the new entry appears.

Troubleshooting

"Theme added successfully!" instead of "Theme updated successfully!" You omitted the key or themeId field in the upload request. A new theme document was created instead of updating the existing one. Delete the duplicate and re-upload with both fields.

Validation log shows only the latest entry The CMS retains the last 20 entries. If you see fewer, the theme is relatively new with few uploads. Older entries beyond 20 are pruned automatically.

Deployment log not created after re-upload Deployment logs are only created when the re-uploaded theme is the currently selected (active) theme for the tenant. If the theme is in the library but not selected, no deployment log is generated.

Cannot find the theme key The theme key is assigned during the first upload. If you uploaded via the admin UI without specifying a key, a UUID was generated automatically. Find it in the theme document details in the CMS admin.

Uploading themes -- How to package and upload a theme
Deployment checklist -- Pre-upload validation checklist
Theme manifest reference -- How the manifest is structured
LocalStage CLI reference -- Local development and validation commands

Versioning and rollback

On this page