feat(release): automate GitHub extension releases

Add Release Please versioning and publish verified Chromium and Firefox artifacts with checksums.

Author: johnnyjoygh

.github/workflows/ci.yml

@@ -29,3 +29,4 @@ jobs:
       - run: pnpm build
       - run: pnpm audit --prod
       - run: node scripts/package.mjs firefox
+      - run: node scripts/package.mjs release

.github/workflows/release-please.yml

@@ -0,0 +1,35 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check release token
+        env:
+          RELEASE_PLEASE_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+        run: |
+          if [ -z "$RELEASE_PLEASE_TOKEN" ]; then
+            echo "RELEASE_PLEASE_TOKEN must be set so generated tags can trigger release.yml." >&2
+            exit 1
+          fi
+      - name: Run release-please
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.github/workflows/release.yml

@@ -0,0 +1,121 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+    env:
+      VITE_CLERK_OAUTH_CLIENT_ID: ${{ vars.VITE_CLERK_OAUTH_CLIENT_ID }}
+      VITE_CLERK_OAUTH_ISSUER: ${{ vars.VITE_CLERK_OAUTH_ISSUER }}
+      VITE_WEB_APP_URL: ${{ vars.VITE_WEB_APP_URL }}
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Validate release configuration
+        id: version
+        run: |
+          for name in \
+            VITE_CLERK_OAUTH_CLIENT_ID \
+            VITE_CLERK_OAUTH_ISSUER \
+            VITE_WEB_APP_URL
+          do
+            if [ -z "${!name}" ]; then
+              echo "Required release variable or secret is missing: $name" >&2
+              exit 1
+            fi
+          done
+
+          package_version="$(node -p "require('./package.json').version")"
+          if [ "$GITHUB_REF_NAME" != "v${package_version}" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match package.json version ${package_version}." >&2
+            exit 1
+          fi
+          echo "VERSION=${package_version}" >> "$GITHUB_ENV"
+          echo "version=${package_version}" >> "$GITHUB_OUTPUT"
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Verify release source
+        run: |
+          pnpm lint
+          pnpm test
+      - name: Build release packages
+        run: pnpm package:release
+      - name: Download signed Firefox package
+        run: |
+          metadata="$(mktemp)"
+          trap 'rm -f "$metadata"' EXIT
+          curl --fail --location --retry 3 --proto '=https' --proto-redir '=https' \
+            https://addons.mozilla.org/api/v5/addons/addon/memos-web-clipper/ \
+            --output "$metadata"
+
+          amo_version="$(jq -r '.current_version.version // empty' "$metadata")"
+          download_url="$(jq -r '.current_version.file.url // empty' "$metadata")"
+          if [ "$amo_version" != "$VERSION" ] || [ -z "$download_url" ]; then
+            echo "Firefox Add-ons publishes ${amo_version:-no version}; expected ${VERSION}. Publish the release candidate there before merging the Release Please PR." >&2
+            exit 1
+          fi
+
+          curl --fail --location --retry 3 --proto '=https' --proto-redir '=https' \
+            "$download_url" \
+            --output "artifacts/memos-web-clipper-firefox-v${VERSION}.xpi"
+      - name: Verify release packages
+        run: |
+          verify_stage="$(mktemp -d)"
+          trap 'rm -rf "$verify_stage"' EXIT
+          mkdir "$verify_stage/unsigned-firefox" "$verify_stage/signed-firefox"
+          unzip -p "artifacts/memos-web-clipper-chromium-v${VERSION}.zip" manifest.json > "$verify_stage/chromium.json"
+          unzip -p "artifacts/memos-web-clipper-firefox-v${VERSION}.xpi" manifest.json > "$verify_stage/firefox.json"
+          unzip -q "artifacts/memos-web-clipper-firefox-v${VERSION}.zip" -d "$verify_stage/unsigned-firefox"
+          unzip -q "artifacts/memos-web-clipper-firefox-v${VERSION}.xpi" -d "$verify_stage/signed-firefox"
+          rm -rf "$verify_stage/signed-firefox/META-INF"
+          diff -qr "$verify_stage/unsigned-firefox" "$verify_stage/signed-firefox"
+
+          node --input-type=module - "$verify_stage" "$VERSION" <<'NODE'
+          import { readFileSync } from "node:fs";
+          import { join } from "node:path";
+
+          const [stage, version] = process.argv.slice(2);
+          const chromium = JSON.parse(readFileSync(join(stage, "chromium.json"), "utf8"));
+          const firefox = JSON.parse(readFileSync(join(stage, "firefox.json"), "utf8"));
+          if (chromium.version !== version || !chromium.key) throw new Error("Chromium release manifest has the wrong version or identity key.");
+          if (firefox.version !== version) throw new Error("Firefox release manifest has the wrong version.");
+          if (firefox.browser_specific_settings?.gecko?.id !== "web-clipper@usememos.com") {
+            throw new Error("Firefox release manifest has the wrong add-on ID.");
+          }
+          NODE
+      - name: Generate checksums
+        working-directory: artifacts
+        run: |
+          sha256sum \
+            "memos-web-clipper-chromium-v${VERSION}.zip" \
+            "memos-web-clipper-firefox-v${VERSION}.xpi" \
+            > SHA256SUMS
+      - name: Publish release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          files: |
+            artifacts/memos-web-clipper-chromium-v${{ steps.version.outputs.version }}.zip
+            artifacts/memos-web-clipper-firefox-v${{ steps.version.outputs.version }}.xpi
+            artifacts/SHA256SUMS

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

README.md

@@ -7,6 +7,20 @@ Save pages, selections, and images directly to your Memos instance. Available fo
 - [Chrome Web Store](https://chromewebstore.google.com/detail/memos-web-clipper/nebaoebnljalfegiidibihhkebeiklbl)
 - [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/memos-web-clipper/)
 
+### Manual installation
+
+Versioned packages and checksums are available from [GitHub Releases](https://github.com/usememos/web-clipper/releases). Store installation is recommended for automatic updates.
+
+For Chromium-based browsers:
+
+1. Download and extract `memos-web-clipper-chromium-v<version>.zip`.
+2. Open the browser's extensions page, such as `chrome://extensions` or `edge://extensions`.
+3. Enable **Developer mode**, choose **Load unpacked**, and select the extracted directory.
+
+For Firefox, download `memos-web-clipper-firefox-v<version>.xpi` and open it with Firefox. GitHub release XPIs are the same Mozilla-signed packages published on Firefox Add-ons.
+
+To verify a download on Linux, run `sha256sum --ignore-missing -c SHA256SUMS` in the directory containing the downloaded package. Do not rely on manually installed packages receiving browser-store-managed updates; check GitHub Releases for new versions.
+
 ## Features
 
 - Capture the page title, URL, and readable description.

docs/RELEASING.md

@@ -0,0 +1,38 @@
+# Releasing
+
+Release Please maintains the release pull request, `CHANGELOG.md`, `package.json` version, Git tag, and GitHub Release. A separate tag workflow verifies the source, builds the extension packages, mirrors the matching Mozilla-signed XPI, generates checksums, and attaches the user-facing assets.
+
+## Repository configuration
+
+Add a fine-grained personal access token as the `RELEASE_PLEASE_TOKEN` Actions secret. It needs read/write access to repository contents, issues, and pull requests. A separate token is required because tags created with the default `GITHUB_TOKEN` do not trigger the tag-based release workflow.
+
+Add these public build values as Actions repository variables:
+
+- `VITE_CLERK_OAUTH_CLIENT_ID`
+- `VITE_CLERK_OAUTH_ISSUER`
+- `VITE_WEB_APP_URL`
+
+The release workflow rejects missing values and verifies that the tag exactly matches the version in `package.json`.
+
+## Release process
+
+1. Merge conventional commits into `main`. Release Please creates or updates a release pull request.
+2. Check out the release pull request branch, configure the production `VITE_*` values in `.env`, and run `pnpm package` from a clean worktree.
+3. Test the generated packages and submit the Firefox ZIP plus its matching source archive to Firefox Add-ons. Submit the Chromium store packages as appropriate.
+4. Wait until Firefox Add-ons publishes the exact version proposed by the release pull request.
+5. Merge the release pull request.
+6. Release Please creates the `v<version>` tag and GitHub Release. The tag workflow builds the same Firefox payload, downloads the signed XPI from Firefox Add-ons, compares every non-signature file, and publishes the release assets only when they match.
+
+If Firefox Add-ons does not yet expose the expected version, the release workflow fails without publishing mismatched artifacts. Publish the store version and rerun the failed workflow.
+
+The public release contains:
+
+- `memos-web-clipper-chromium-v<version>.zip`, which retains the public manifest key needed for a stable OAuth extension ID.
+- `memos-web-clipper-firefox-v<version>.xpi`, mirrored from Firefox Add-ons after payload verification.
+- `SHA256SUMS` for both packages.
+
+Store upload archives remain separate. `pnpm package` produces those archives, while `pnpm package:release` produces the Chromium sideload archive and an unsigned Firefox archive used only to verify the signed store package.
+
+## Bootstrap
+
+Version `0.1.0` was published before Release Please was introduced. The manifest records it as the current release, and `bootstrap-sha` points at the initial extension commit so later conventional commits are included in the first generated release pull request. Once the first Release Please release is complete, the bootstrap setting can be removed.

package.json

@@ -10,6 +10,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "package": "pnpm build && node scripts/package.mjs all",
+    "package:release": "pnpm build && node scripts/package.mjs release",
     "package:chrome": "pnpm build && node scripts/package.mjs chrome",
     "package:edge": "pnpm build && node scripts/package.mjs edge",
     "package:firefox": "pnpm build && node scripts/package.mjs firefox",

release-please-config.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-v-in-tag": true,
+  "include-component-in-tag": false,
+  "bump-minor-pre-major": true,
+  "bootstrap-sha": "d22945071e2c63a1b25b75278b46c503a01c608c",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@usememos/web-clipper",
+      "changelog-path": "CHANGELOG.md",
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance Improvements" },
+        { "type": "deps", "section": "Dependencies" },
+        { "type": "revert", "section": "Reverts" }
+      ]
+    }
+  }
+}

scripts/package.mjs

@@ -1,4 +1,4 @@
-// Builds store-specific upload archives from one fresh dist/ build.
+// Builds store-upload and manual-release archives from one fresh dist/ build.
 //
 // Chromium stores share the exact same package. Firefox needs an MV3 background
 // script fallback, a stable Gecko ID, and data-collection declarations. AMO also
@@ -19,7 +19,7 @@ const FIREFOX_ADDON_ID = "web-clipper@usememos.com";
 // Firefox desktop gained built-in data consent in 140; Android gained it in 142.
 // `gecko.strict_min_version` covers both unless a separate Android manifest is used.
 const FIREFOX_MIN_VERSION = "142.0";
-const VALID_TARGETS = new Set(["all", "chrome", "edge", "firefox"]);
+const VALID_TARGETS = new Set(["all", "release", "chrome", "edge", "firefox"]);
 
 const requestedTarget = process.argv[2] ?? "all";
 if (!VALID_TARGETS.has(requestedTarget)) {
@@ -60,7 +60,7 @@ if (baseManifest.version !== packageJson.version) {
   throw new Error(`Version mismatch: package.json is ${packageJson.version}, dist manifest is ${baseManifest.version}.`);
 }
 
-if (requestedTarget === "all") rmSync(ARTIFACTS, { recursive: true, force: true });
+if (requestedTarget === "all" || requestedTarget === "release") rmSync(ARTIFACTS, { recursive: true, force: true });
 mkdirSync(ARTIFACTS, { recursive: true });
 
 const zipDirectory = (sourceDir, outputPath) => {
@@ -100,13 +100,39 @@ const storeManifest = (target) => {
   return manifest;
 };
 
-const createStoreStage = (target) => {
-  const stage = mkdtempSync(join(tmpdir(), `memos-web-clipper-${target}-`));
+const manualChromiumManifest = () => {
+  const manifest = structuredClone(baseManifest);
+  // Manual Chromium installs need the public key so chrome.identity uses the
+  // registered store extension ID regardless of the extracted directory.
+  if (!manifest.key) throw new Error("The manual Chromium package requires a manifest key to preserve its OAuth identity.");
+  delete manifest.update_url;
+  return manifest;
+};
+
+const createStage = (label, manifest) => {
+  const stage = mkdtempSync(join(tmpdir(), `memos-web-clipper-${label}-`));
   cpSync(DIST, stage, { recursive: true });
-  writeFileSync(join(stage, "manifest.json"), `${JSON.stringify(storeManifest(target), null, 2)}\n`);
+  writeFileSync(join(stage, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
   return stage;
 };
 
+const createStoreStage = (target) => {
+  return createStage(target, storeManifest(target));
+};
+
+const packageReleaseChromium = () => {
+  const stage = createStage("chromium-release", manualChromiumManifest());
+  const outputPath = join(ARTIFACTS, `memos-web-clipper-chromium-v${packageJson.version}.zip`);
+
+  try {
+    zipDirectory(stage, outputPath);
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+
+  return outputPath;
+};
+
 const packageChromium = (targets) => {
   const stage = createStoreStage("chromium");
   const chromePath = join(ARTIFACTS, `memos-web-clipper-chrome-v${packageJson.version}.zip`);
@@ -170,7 +196,7 @@ const packageFirefoxSource = () => {
   return sourcePath;
 };
 
-const packageFirefox = () => {
+const packageFirefox = ({ includeSource = isGitCheckout } = {}) => {
   const stage = createStoreStage("firefox");
   const firefoxPath = join(ARTIFACTS, `memos-web-clipper-firefox-v${packageJson.version}.zip`);
 
@@ -185,10 +211,16 @@ const packageFirefox = () => {
     rmSync(stage, { recursive: true, force: true });
   }
 
-  return { firefoxPath, sourcePath: isGitCheckout ? packageFirefoxSource() : null };
+  return { firefoxPath, sourcePath: includeSource && isGitCheckout ? packageFirefoxSource() : null };
 };
 
 const created = [];
+if (requestedTarget === "release") {
+  created.push(packageReleaseChromium());
+  const { firefoxPath, sourcePath } = packageFirefox({ includeSource: false });
+  created.push(firefoxPath);
+  if (sourcePath) created.push(sourcePath);
+}
 if (requestedTarget === "all" || requestedTarget === "chrome" || requestedTarget === "edge") {
   created.push(...packageChromium(requestedTarget === "all" ? ["chrome", "edge"] : [requestedTarget]));
 }
@@ -198,6 +230,6 @@ if (requestedTarget === "all" || requestedTarget === "firefox") {
   if (sourcePath) created.push(sourcePath);
 }
 
-console.log("\nCreated store artifacts:");
+console.log("\nCreated artifacts:");
 for (const file of created) console.log(`- artifacts/${basename(file)}`);
 console.log("\ndist/ remains the unpacked development build with its stable Chrome key.");