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.

Steps

1. Understand version tracking

Each accepted theme upload generates a manifestRevision timestamp in ISO 8601 format (e.g. 2025-06-15T14:30:00.000Z). It marks when the current manifest was generated; it is not a restorable version number.

The CMS stores additional data per version:

Data	Description
Manifest revision	ISO timestamp of the latest accepted upload
Theme manifest	Templates, blocks, and settings definitions from the latest upload
Theme logs	Upload results, error and warning counts, uploader, and manifest changes
Theme ZIP	The package currently stored for the 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.example/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=000000000000000000000001"

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 and a new upload log is recorded. The response confirms the update:

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

3. Review validation history

Each upload appends a theme log entry. The list can include:

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 history is created only when the re-uploaded theme is the currently selected theme for the site.

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:

basker theme dev --theme ./my-theme

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

Check the update

When complete, you will have:

An updated theme with a new manifest revision
Theme logs recording upload results and manifest changes
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.

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 through the admin without specifying one, Basker generated it. Open the theme details to find the key and document ID before using the update API.

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