Staged Rollout #
Release a new version to a percentage of your customers before making it available to everyone.
What Is Staged Rollout? #
Instead of releasing a new version to all customers at once, you release to a small group first (e.g., 10%), monitor for problems, then gradually increase the percentage.
This reduces risk: if a bug exists in the new version, only a fraction of customers are affected before you catch it.
How the Bucketing Works #
Each license is assigned to a deterministic rollout bucket. The bucket is calculated from the license ID using a hash function. This means:
- The same license always falls in the same bucket
- A license in the 10% rollout is also in the 25% rollout, and in the 50% rollout
- Increasing the rollout percentage always includes previously included licenses plus new ones
Example:
- Monday: Rollout 10% — 10 of your 100 customers receive the update
- Wednesday: Rollout 25% — Those same 10, plus 15 more, receive the update
- Friday: Full Rollout — All 100 customers receive the update
Setting Up a Staged Release #
- Edit the version
- Under Update Server Settings, set Rollout Percentage to your starting value (e.g., 10)
- Publish the version
- Monitor update check logs and download logs for errors
- Increase the rollout percentage over time
- When satisfied, click "Full Rollout" in the Versions list or set to 100
Overriding Rollout for Critical Updates #
If you discover a security issue and need to push an emergency fix to all customers immediately:
- Create the fix version
- Set Rollout to 100
- Check "Is Critical Update"
- Publish
Note on Two Code Paths #
The Update Server has two rollout-checking code paths that use slightly different bucketing algorithms:
- The REST API (update checks from client software) uses
crc32(license_id) % 100 - The Customer Portal (available updates page) uses
crc32(license_id|version) % 100
Warning: These two algorithms are NOT equivalent. A license may be eligible for an update via the REST API but not shown as available in the Customer Portal, or vice versa. The discrepancy occurs because the two hash inputs differ (license_id vs license_id|version), meaning the same rollout percentage produces different eligible sets depending on which code path evaluates it. This is not an edge case — it is a structural difference between the two paths. Always use 100% rollout for critical updates to avoid this inconsistency.