Staged Rollouts in the Chrome Web Store

Every extension update reaches users automatically within hours, which is wonderful for fixes and terrifying for regressions: one bad release and every user has it by morning. A staged rollout limits the blast radius — publish to a small percentage of users first, watch the error rate and reviews, and widen only when the numbers look right. The Chrome Web Store supports percentage rollouts for established items, and the technique pairs naturally with remote feature flags and version-tagged error reporting. This guide covers setting one up, deciding when to advance, and what to do when a stage goes wrong. It belongs to extension updates and data migration.

How percentage rollout works

When you publish an update with a rollout percentage, the store serves the new version only to that fraction of users’ update checks; everyone else keeps receiving the previous version. Assignment is stable per installation, so a user in the first 5% stays in it as the percentage grows. You can increase the percentage at any time from the developer dashboard (or the API). You cannot pull the new version back from users who already have it — to undo, you publish a newer version containing the old code. The option is available only to items with an established user base, above a threshold the store sets; small extensions publish to everyone at once and rely on flags and fast fixes instead.

Step-by-step: run a staged rollout

1. Tag every signal with the version

1// sw.js — every error report and usage count carries the running version
2const VERSION = chrome.runtime.getManifest().version;
3self.addEventListener("error", (e) => report({ version: VERSION, message: e.message, stack: e.error?.stack }));
4self.addEventListener("unhandledrejection", (e) => report({ version: VERSION, message: String(e.reason) }));

Execution context: the service worker, and the same in every other context. A staged rollout is only useful if you can compare the new version with the old one at the same time. Version-tagged error reports and active-user counts make that comparison possible — see capturing uncaught errors in every context and counting active users without tracking.

2. Publish with a percentage

1# Chrome Web Store API: upload, then publish to a percentage of users
2curl -X POST "https://www.googleapis.com/chromewebstore/v1.1/items/$ITEM_ID/publish?deployPercentage=5" \
3  -H "Authorization: Bearer $ACCESS_TOKEN" -H "x-goog-api-version: 2" -H "Content-Length: 0"

Execution context: CI or a terminal with Chrome Web Store API credentials. The dashboard offers the same control on the package’s publishing page. Review still happens first; the percentage applies once the version is approved. Record the version and percentage in your release log so the monitoring dashboard can annotate the stage. See automating Chrome Web Store uploads with the API.

3. Compare new and old versions side by side

1SELECT version,
2       COUNT(DISTINCT install_bucket) AS installs,
3       SUM(errors) * 1.0 / NULLIF(SUM(sessions), 0) AS errors_per_session
4FROM daily_version_stats
5WHERE day >= :rollout_start AND version IN (:new_version, :old_version)
6GROUP BY version;

Execution context: your analytics backend. Absolute error counts grow with the rollout percentage; rates per session or per active install are comparable. Look at the top new error signatures in the new version, not just the overall rate — a new crash affecting one feature can hide in a stable total. Compare against the old version over the same days, so weekday effects cancel out.

4. Advance in steps

Raise the percentage only after each stage has run long enough to include ordinary usage — at least a full day, ideally including a weekday — and the comparison is clean. Typical steps are 1%, 5%, 20%, 50%, 100%, but the right schedule depends on your user count: at 1% of 20,000 users you see 200 installs, enough to catch crashes but not subtle regressions. Releases containing data migrations deserve slower stages, because a migration bug cannot be undone by a rollback.

5. Halt with flags, roll back with a new version

1// flags.json — immediate mitigation while a fix is prepared
2{ "version": 58, "flags": { "newExporter": false } }

Execution context: the remote flags document read by the extension. The fastest response to a regression in a flagged feature is to turn the flag off for everyone: it takes effect within the flag refresh interval, without store review. For unflagged regressions, publish a new version — a higher version number containing the previous code, or the fix — at 100%, which supersedes the bad version for everyone. See rolling back a bad extension release.

6. Combine store rollout with in-extension flags

Store rollouts control which code users run; feature flags control which behaviour that code exhibits. Shipping risky features dark, rolling out the version to 100%, and then ramping the feature flag gives finer control and instant reversal — useful for extensions below the store’s rollout threshold too. See remote feature flags without remote code.

7. Write the rollout down

Keep a release log with the version, each percentage change, the time, the metrics you looked at, and who decided. When something does go wrong weeks later, that log tells you which users had which version when — information otherwise lost.

Common mistakes

• No version tags on errors. You cannot compare new and old.
• Comparing absolute counts. They scale with the percentage.
• Advancing on a schedule rather than on evidence. The point is to look.
• Expecting to “unpublish” a version. You can only publish forward.
• Fast rollouts for migrations. Data changes cannot be rolled back.

Cross-browser variation

• Chrome / Edge: Chrome Web Store percentage rollouts for eligible items. Edge Add-ons has its own submission process; check its current options for gradual release, and otherwise rely on flags.
• Firefox: AMO does not offer percentage rollouts for listed add-ons; staged releases are possible for self-hosted add-ons via the update manifest, and flags work everywhere.
• Safari: App Store Connect offers phased release for app updates over seven days, which applies to the containing app and therefore the extension.

Verification

1. Publish a test update at a small percentage and confirm the dashboard shows the rollout state.
2. Confirm error reports and usage counts are segmented by version in your dashboards.
3. Practise a rollback in a staging item: publish a higher version with the old code and confirm clients update to it.
4. Toggle a feature flag off and confirm the change reaches clients within the refresh interval.

FAQ

Can I choose which users get the rollout?

No. The store assigns installations randomly and stably.

Does a staged rollout delay review?

No. Review happens once; the percentage applies after approval.

What if my extension is below the rollout threshold?

Use feature flags for risky changes and keep a rollback version ready.

How many users do I need for a meaningful first stage?

Enough that the new version produces several hundred sessions within a day. With fewer, a crash affecting a small feature may simply not occur. Small extensions can treat the first stage as “internal and beta users” through a separate unlisted item instead.

Should the rollout pause over weekends?

If your users are mostly working professionals, weekend usage is unrepresentative. Avoid advancing a stage on data gathered only over a weekend.

Related

• Rolling back a bad extension release — when a stage fails.
• Alerting on error spikes after a release — automating the monitoring.
• Testing an update before you publish it — catching issues before stage one.
• Extension updates and data migration — the parent topic.