Versioning & Updates

How semantic versioning works on Kyper and what happens when you ship updates.

Semantic versioning

Kyper requires all versions to follow semantic versioning: MAJOR.MINOR.PATCH. Each push must be higher than the current published version — Kyper rejects versions equal to or less than what's already live in the marketplace.

You can freely re-push the same version number while it's still pending, building, failed, or in review. Kyper automatically replaces the previous submission with your new build. Once a version is published, the version number is locked — bump to move forward.

Use the kyper tag command to bump versions in your kyper.yml:

bash 
kyper tag --bump patch   # 1.0.0 → 1.0.1
kyper tag --bump minor   # 1.0.0 → 1.1.0
kyper tag --bump major   # 1.0.0 → 2.0.0

Update policy

How your version bump affects consumers with active hosted deployments:

PATCH / MINOR

Auto-deployed

Patch and minor updates are automatically deployed to all running consumer instances. The new image is pulled, containers are restarted, and the on_update hook runs.

MAJOR

Consumer opt-in

Major updates require consumer opt-in. Consumers see an upgrade banner on their deployment page and must explicitly choose to upgrade. This protects them from breaking changes.

Lifecycle hooks

Hooks run inside your web container after the containers start or restart. Common use: database migrations.

Hook Runs when On failure
on_deploy New deployment is first provisioned Deployment marked as failed, consumer + admin notified
on_update Existing deployment is updated to a new version Automatic rollback to the previous version

Rollback behavior: If an on_update hook fails (non-zero exit), Kyper automatically re-deploys the previous version's image, restarts containers, and emails both you and the consumer. The failed version stays in your portal for debugging.

Best practices

  • ✓
    Bump patch for bug fixes, security patches, and dependency updates
  • ✓
    Bump minor for new features that are backward-compatible
  • ✓
    Bump major for breaking changes (new required env vars, schema changes that need manual intervention, removed features)
  • ✓
    Always set on_update if your app has a database — this ensures migrations run on every update
  • ✓
    Test locally before pushing — run kyper check and test your Docker build locally before pushing to Kyper