Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 · Publishing

Updates, Versioning, Localization and CI

Ship extension updates safely with semantic versioning, staged rollout, onInstalled migrations, _locales translations and an automated build and publish pipeline using the Chrome Web Store API.

Publishing once is the start. A real extension is updated for years, and each update reaches thousands of browsers automatically. That is powerful and risky: a broken release spreads fast, and a new permission can switch your extension off for every user. This lesson covers versioning, staged releases, translations and an automated pipeline.

How updates reach users

Chrome checks for extension updates every few hours. When you publish a new version, installed copies update in the background and run the new code after a restart or the next time the worker starts. You do not control the exact moment, so your code must cope with old data and mixed states for a while.

flowchart LR
    D["Developer uploads v1.2.0"] --> R["Review"]
    R --> S["Store publishes"]
    S --> C["Chrome checks hourly"]
    C --> U["Update installed"]
    U --> O["runtime.onInstalled (reason: update)"]

onInstalled runs once per update: the place to migrate data.

Versioning

The manifest version must increase with every upload. Use a simple scheme like semantic versioning:

  • Patch (1.0.1): bug fixes only.
  • Minor (1.1.0): new features, same permissions.
  • Major (2.0.0): big changes, data migrations or new permissions.

Chrome accepts one to four integer parts without leading zeros or letters: 1.2.3-beta is invalid. If you want pre-release labels, put them in version_name, which is a display string:

JSON
{ "version": "1.2.0", "version_name": "1.2.0 beta 3" }
Compare and bump versions

Note that 1.10.0 is newer than 1.9.0: versions compare number by number, not as text.

Safe release habits

  • Test the zip, not the source folder.
  • Release in stages: the dashboard lets you set a rollout percentage for a new version (for example 10 percent, then 100) so a bug hits few users. Combine it with a quick way to publish a patch.
  • Add no new warning permissions in a patch. A new permission that triggers a warning disables the extension for users until they approve; many never notice. Prefer optional permissions, or batch permission changes into one clearly announced major release.
  • Keep a rollback plan: you cannot lower a version, so the rollback is a new, higher version containing the old code.
  • Migrate data on update with runtime.onInstalled, as shown in Storage patterns.
  • Show what changed. Use reason === "update" to open a short release-notes page, sparingly.
JavaScript
// service-worker.js (real extension code)
chrome.runtime.onInstalled.addListener(({ reason, previousVersion }) => {
  if (reason === "install") chrome.tabs.create({ url: "welcome.html" });
  if (reason === "update") console.log("Updated from", previousVersion);
});

Localization with _locales

To reach a global audience, translate the user-visible strings. Create folders per language:

Text
_locales/
  en/messages.json
  es/messages.json
  de/messages.json
JSON
{
  "extName": { "message": "Price Marker" },
  "extDescription": { "message": "Highlights prices on shopping pages." },
  "saved": { "message": "Saved $COUNT$ items", "placeholders": { "count": { "content": "$1" } } }
}

Reference them in the manifest with __MSG_name__ and set a default language:

JSON
{
  "name": "__MSG_extName__",
  "description": "__MSG_extDescription__",
  "default_locale": "en"
}

In code use chrome.i18n.getMessage("saved", [String(n)]), and in HTML copy the message into elements at load. Chrome picks the user's language, falls back to default_locale and shows the matching store listing text if you also translate the listing in the dashboard.

A getMessage stand-in

Automating the release

A repeatable pipeline prevents "works on my machine" releases:

  1. Test (unit tests, then E2E from the previous lessons).
  2. Bump the version in manifest.json (a script or npm version).
  3. Build and zip the output.
  4. Upload and publish with the Chrome Web Store API.

The Web Store API uses OAuth: you create a Google Cloud project, enable the Chrome Web Store API and obtain a client id, client secret and refresh token once. A CI job then calls "upload" and "publish". Community tools such as chrome-webstore-upload-cli wrap it. A GitHub Actions workflow, shown read-only:

YAML
# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci && npm test && npm run build
      - run: cd dist && zip -r ../extension.zip .
      - run: npx chrome-webstore-upload-cli upload --source extension.zip --auto-publish
        env:
          EXTENSION_ID: ${{ secrets.EXTENSION_ID }}
          CLIENT_ID: ${{ secrets.CLIENT_ID }}
          CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }}
          REFRESH_TOKEN: ${{ secrets.REFRESH_TOKEN }}

Store the OAuth values as CI secrets, never in the repository. The submission still goes through Google's review.

Check your understanding

Quick check · 4 questions

of 4 answered You scored / 4 · perfect!

  1. 1. Which version string is valid for the manifest?

    One to four dot-separated integers. Put labels like beta in version_name.
  2. 2. What is the safest way to fix a bad release?

    Version numbers only go up, so a rollback is a new higher version.
  3. 3. Where do you run a data migration after an update?

    onInstalled fires once after install or update.
  4. 4. Which manifest value uses a translated string?

    Manifest strings reference _locales messages with MSG_key, plus a default_locale.

Summary

  • Updates install automatically; handle old data with onInstalled migrations.
  • Versions are up to four integers; use version_name for labels; roll back with a higher version.
  • Stage rollouts and avoid new warning permissions in patches.
  • Translate with _locales and chrome.i18n; automate test, build, zip and upload in CI.

Next: Project: Page Notes Extension