SveltyCMS uses a simple two-branch model with automated releases triggered when CI passes on main.

Branch Model

Branch	Purpose	Releases
next	Active development — features, fixes, and experiments land here first	No
main	Production — merged from next when stable	Yes (auto on CI pass)

Release Pipeline

next:   bump package.json version → commit → merge to main
                 │
                 ▼
main:   CI runs (whitebox → build → DB matrix → bench → E2E)
                 │
                 ▼ (CI passes)
        auto-release triggers:
        1. reads version from package.json
        2. creates git tag (e.g. v0.0.9)
        3. npm publish
        4. GitHub Release with auto-generated notes

        version matches between package.json and git tag ✅

The package.json version flows naturally from next → main through merges. When CI passes on main, the release happens automatically — no separate tag or manual step needed. A manual trigger is also available at Actions → Auto Release → Run workflow for emergency releases.

---

Version Pipeline Components

Component	Path	Role
Version Service	src/services/core/version-service.ts	Reads local version from package.json, checks GitHub Releases API for newer versions
Version Handler	src/routes/api/[...path]/handlers/version.ts	REST endpoint /api/system/version/check — serves update status to the admin UI
VersionCheck Component	src/components/version-check.svelte	Admin UI badge — displays current version with green/yellow/grey status
Version Tests	tests/unit/api/version.test.ts	Unit tests for isNewer comparison logic and API response shapes
Auto Release	.github/workflows/auto-release.yaml	Waits for CI pass on main, then tags, publishes, and creates GitHub Release

Note: src/utils/media/version-history.ts is a separate module for tracking media file revisions (create/update/replace diffs) — not related to CMS release versioning.

---

API Endpoints

Check for Updates

GET /api/system/version/check

Queries the GitHub Releases API and compares against the installed version from package.json.

Response (update available):

{
  "success": true,
  "data": {
    "currentVersion": "0.0.7",
    "latestVersion": "0.0.8",
    "updateAvailable": true,
    "checkedAt": "2026-07-08T12:00:00.000Z"
  }
}

Response (up to date):

{
  "success": true,
  "data": {
    "currentVersion": "0.0.7",
    "latestVersion": "0.0.7",
    "updateAvailable": false,
    "checkedAt": "2026-07-08T12:00:00.000Z"
  }
}

If GitHub is unreachable, the endpoint returns latestVersion: null with updateAvailable: false and an error field.

---

Admin UI

The VersionCheck component (src/components/version-check.svelte) appears in the admin interface and:

• Reads PKG_VERSION from publicEnv (loaded from package.json at server boot via settings-service.ts → +layout.server.ts)
• Fetches /api/system/version/check every hour to compare against the latest GitHub release
• Shows a clickable badge linking to the releases page

Badge State	Meaning
Green (success)	You are up to date
Yellow (warning)	A newer version is available (e.g. “Update to v0.0.8 recommended”)
Grey (surface)	Could not check for updates (network/GitHub API issue)

---

Automated Upgrades

SveltyCMS includes an automated upgrade CLI:

bun run scripts/upgrade.ts

The script:

1. Fetches the latest release from GitHub
2. Merges changes into your local branch
3. Refreshes dependencies (bun install)

Always run bun run check && bun run test:unit after an upgrade to ensure system integrity.

---

File Version History

For media file version tracking (distinct from CMS release versioning), SveltyCMS uses src/utils/media/version-history.ts which provides:

• createVersion() — records file create/update/replace actions with change diffs
• compareVersions() — compares two file versions for content and metadata changes
• detectChanges() — deep-diff comparison between old and new file metadata
• getVersionStats() — aggregates version counts, sizes, and user activity

This powers the media gallery’s version history viewer — not the CMS release cycle.

---

Related

• Upgrading SveltyCMS — Manual upgrade process
• System Settings — Configure your SveltyCMS instance
• Git Workflow — Branch strategy and CI gates