Apply CloudSmith platform updates

CloudSmith checks for new releases automatically and notifies you when an update is available. You can apply updates from the portal, the CLI, or the PowerShell module.

How update checks work

CloudSmith polls the GitHub releases API every 10 minutes. When a new version is detected, a banner appears at the top of the portal:

CloudSmith v0.6.0 is available — View release notes  Apply update

The check compares the currently running image tag against the latest published release. In air-gapped environments where ghcr.io is unreachable, disable the check by setting CLOUDSMITH_UPDATE_CHECK_ENABLED=false in your configuration. See Configuration reference for details.

Apply an update — portal

  1. Click the Apply update link in the update banner, or navigate to Platform Management → Platform Updates.
  2. Review the version number and release notes link.
  3. Click Apply Update.

The portal shows a progress indicator while the update runs. Do not close the browser tab — if you navigate away, the update continues in the background and you can check status by returning to Platform Management → Platform Updates.

When the update completes, the portal reloads automatically and the banner is cleared.

Apply an update — CLI

Check whether an update is available:

cs platform update --check

Current version:  0.5.3
Latest version:   0.6.0
Update available: Yes
Release notes:    https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/tag/v0.6.0

Apply the latest available update:

cs platform update --apply

Wait for the update to complete before returning:

cs platform update --apply --wait

Applying update: 0.5.3 → 0.6.0
Job ID: job_02hz...
... updating (42s)
Status: Completed

CloudSmith updated to v0.6.0 successfully.

Apply a specific version:

cs platform update --apply --version 0.5.2

See cs CLI reference — cs platform update for the full flag reference.

Apply an update — PowerShell

Check for available updates:

Update-CloudSmith -Check

CurrentVersion : 0.5.3
LatestVersion  : 0.6.0
UpdateAvailable: True
ReleaseNotesUrl: https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/tag/v0.6.0

Apply the latest available update:

Update-CloudSmith -Apply

Apply a specific version:

Update-CloudSmith -Apply -TargetVersion 0.6.0

Preview what the update would do without making changes:

Update-CloudSmith -Apply -WhatIf

See PowerShell module reference — Update-CloudSmith for all parameters.

On-premises vs PaaS — what happens during an update

The update mechanism differs between deployment models.

On-premises

On-premises deployments run as a Docker Compose stack inside a Linux VM (cloudsmith-docker) on your management host.

When you apply an update:

  1. The relay agent downloads the new container images from ghcr.io to the VM.
  2. The agent performs a rolling restart of the Docker Compose stack — containers are restarted one at a time to minimize downtime.
  3. The cloudsmith-api and cloudsmith-portal containers are replaced with the new image versions.
  4. The stack comes back up on the new version.

A VM reboot is not required for standard updates. Downtime is typically 30–60 seconds while the containers restart.

Air-gapped environments: If the CloudSmith VM cannot reach ghcr.io, the update cannot pull new images automatically. Use the bundled update path — download a new bundled package on a connected machine, transfer it to the management host, and run the installer with the new bundle. See Bundled install — updating for the procedure.

PaaS (Azure Container Apps)

PaaS deployments run on Azure Container Apps. When you apply an update:

  1. CloudSmith creates a new ACA revision with the updated container image tag.
  2. Azure Container Apps performs a zero-downtime rolling revision swap — traffic shifts to the new revision while the old revision drains active connections.
  3. The old revision is deactivated once all connections have drained.

There is no service interruption during a PaaS update under normal conditions.

Roll back an update

If an update produces unexpected behavior, roll back to the previous version.

Portal

Navigate to Platform Management → Platform Updates → Revision history. Select the previous version and click Roll back to this version.

CLI

cs platform update --rollback

PowerShell

Update-CloudSmith -Rollback

The rollback redeploys the previously running image tag. On PaaS, this creates a new ACA revision pointing to the previous image. On-premises, the Docker Compose stack is restarted with the previous image version.

Note: Rollback restores the application to the prior version but does not reverse database schema migrations that were applied during the update. If the update included schema changes, contact CloudSmith support before rolling back in a production environment.