Skip to content

Build your personal knowledge base with Trilium Notes

ci(web-clipper): submit releases to the Chrome Web Store and Firefox Add-ons

Elian Doran14a8791df602
diff --git a/.claude/skills/developing-web-clipper/SKILL.md b/.claude/skills/developing-web-clipper/SKILL.md
index a0d467cd55..01f578b8c6 100644
--- a/.claude/skills/developing-web-clipper/SKILL.md
+++ b/.claude/skills/developing-web-clipper/SKILL.md
@@ -212,13 +212,25 @@ CI (`.github/workflows/web-clipper.yml`) builds both zips; it runs no tests, so
`web-clipper-v*` tag ships whatever the tagged commit holds — the tests run only in `dev.yml`, on
pushes and pull requests.
-**Mozilla's review rebuilds from the sources zip.** `zip.sourcesRoot` is the repository root and
-`zip.includeSources` an allowlist (WXT 0.21): the workspace files and lockfile, `apps/web-clipper`,
-and the `apps/client` stylesheets and fonts the pages import. A new import from outside
-`apps/web-clipper` goes on that list. The `zip:sources:done` hook adds the Chrome-only offscreen
-page, which WXT leaves out, and copies `README.md` (the reviewer's build instructions) to the
-archive root. WXT prints "Could not get stats of '…'" for every file of the sources zip, because it
-looks the paths up from the package directory rather than `sourcesRoot`; the archive is complete.
+- **Mozilla's review rebuilds from the sources zip.** `zip.sourcesRoot` is the repository root and
+ `zip.includeSources` an allowlist (WXT 0.21): the workspace files and lockfile,
+ `apps/web-clipper`, and the `apps/client` stylesheets and fonts the pages import. A new import
+ from outside `apps/web-clipper` goes on that list. The `zip:sources:done` hook adds the Chrome-only
+ offscreen page, which WXT leaves out, and copies `README.md` (the reviewer's build instructions)
+ to the archive root.
+- **CI proves the zip builds**: it unzips it into `$RUNNER_TEMP`, installs with
+ `--filter web-clipper`, builds Firefox and `diff -r`s the result against the regular build. WXT
+ prints "Could not get stats of '…'" for every file of the sources zip, because it looks the paths up
+ from the package directory rather than `sourcesRoot`; the archive is complete.
+- **Tags**: `web-clipper-v*-rc*` signs the Firefox build on AMO's unlisted channel (`web-ext sign`)
+ and makes a GitHub pre-release with the `.xpi`. Any other tag makes a release and submits to both
+ stores with `wxt submit` (publish-browser-extension), one matrix job per store, so a failed store
+ re-runs alone. A manual run of the workflow does a `--dry-run` of the submission. The Chrome Web
+ Store uses API v2 with a service account (v1.1 shuts down on 2026-10-15); the private key secret is
+ the PEM with real line breaks, as the library does not unescape `\n`.
+- **Versions are numeric and single-use** in both stores, and WXT cuts a `package.json` version like
+ `1.2.0-rc1` down to `1.2.0`, so an RC carries a version below the final one (`1.1.90`) and the
+ tag alone says "rc".
To compare bundle sizes with `main`, build it in a temporary `git worktree` (never stash). `main`
may still need dependencies the branch removed (`cash-dom`): give the worktree its own
diff --git a/.github/workflows/web-clipper.yml b/.github/workflows/web-clipper.yml
index e087296ba4..dceda863dd 100644
--- a/.github/workflows/web-clipper.yml
+++ b/.github/workflows/web-clipper.yml
@@ -13,6 +13,8 @@ on:
paths:
- "apps/web-clipper/**"
+ workflow_dispatch:
+
permissions:
contents: write
discussions: write
@@ -21,6 +23,10 @@ concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
+env:
+ IS_TAG: ${{ startsWith(github.ref, 'refs/tags/web-clipper-v') }}
+ IS_RC: ${{ startsWith(github.ref, 'refs/tags/web-clipper-v') && contains(github.ref, '-rc') }}
+
jobs:
build:
runs-on: ubuntu-latest
@@ -48,9 +54,19 @@ jobs:
pnpm --filter web-clipper zip
pnpm --filter web-clipper zip:firefox
+ - name: Rebuild the Firefox extension from the sources zip
+ run: |
+ sources="$RUNNER_TEMP/sources"
+ mkdir "$sources"
+ unzip -q apps/web-clipper/.output/*-sources.zip -d "$sources"
+ cd "$sources"
+ pnpm install --filter web-clipper --frozen-lockfile --ignore-scripts
+ pnpm --filter web-clipper build:firefox
+ diff -r apps/web-clipper/.output/firefox-mv2 \
+ "$GITHUB_WORKSPACE/apps/web-clipper/.output/firefox-mv2"
+
- name: Upload build artifacts
uses: actions/upload-artifact@v7
- if: ${{ !startsWith(github.ref, 'refs/tags/web-clipper-v') }}
with:
name: web-clipper-extension
path: apps/web-clipper/.output/*.zip
@@ -59,7 +75,7 @@ jobs:
compression-level: 0
- name: Sign the Firefox extension
- if: ${{ startsWith(github.ref, 'refs/tags/web-clipper-v') }}
+ if: ${{ env.IS_RC == 'true' }}
working-directory: apps/web-clipper
env:
WEB_EXT_API_KEY: ${{ secrets.AMO_JWT_ISSUER }}
@@ -75,14 +91,65 @@ jobs:
- name: Release web clipper extension
uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
- if: ${{ startsWith(github.ref, 'refs/tags/web-clipper-v') }}
+ if: ${{ env.IS_TAG == 'true' }}
with:
draft: false
- prerelease: ${{ contains(github.ref, '-rc') }}
+ prerelease: ${{ env.IS_RC == 'true' }}
fail_on_unmatched_files: true
files: |
apps/web-clipper/.output/*-chrome.zip
- apps/web-clipper/.output/*-firefox.xpi
+ ${{ env.IS_RC == 'true' && 'apps/web-clipper/.output/*-firefox.xpi' || '' }}
discussion_category_name: Releases
make_latest: false
token: ${{ secrets.RELEASE_PAT }}
+
+ publish:
+ needs: build
+ if: ${{ github.event_name == 'workflow_dispatch' || (startsWith(github.ref, 'refs/tags/web-clipper-v') && !contains(github.ref, '-rc')) }}
+ runs-on: ubuntu-latest
+ name: Publish to the ${{ matrix.store }}
+
+ permissions:
+ contents: read
+
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - store: Chrome Web Store
+ zips: --chrome-zip .output/*-chrome.zip
+ - store: Firefox Add-ons
+ zips: --firefox-zip .output/*-firefox.zip --firefox-sources-zip .output/*-sources.zip
+
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+ - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+ - name: Set up node & dependencies
+ uses: actions/setup-node@v7
+ with:
+ node-version: 24
+
+ - name: Install dependencies
+ run: pnpm install --filter web-clipper --frozen-lockfile --ignore-scripts
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: web-clipper-extension
+ path: apps/web-clipper/.output
+
+ - name: Submit for review
+ working-directory: apps/web-clipper
+ env:
+ DRY_RUN_FLAG: ${{ github.event_name == 'workflow_dispatch' && '--dry-run' || '' }}
+ ZIPS: ${{ matrix.zips }}
+ CHROME_API_VERSION: v2
+ CHROME_EXTENSION_ID: ofoiklieachadcaeffficgjaajojpkpi
+ CHROME_PUBLISHER_ID: ${{ secrets.CHROME_PUBLISHER_ID }}
+ CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL: ${{ secrets.CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL }}
+ CHROME_SERVICE_ACCOUNT_PRIVATE_KEY: ${{ secrets.CHROME_SERVICE_ACCOUNT_PRIVATE_KEY }}
+ FIREFOX_EXTENSION_ID: [email protected]
+ FIREFOX_JWT_ISSUER: ${{ secrets.AMO_JWT_ISSUER }}
+ FIREFOX_JWT_SECRET: ${{ secrets.AMO_JWT_SECRET }}
+ run: pnpm exec wxt submit $DRY_RUN_FLAG $ZIPS
diff --git a/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md b/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
index fbe26ffc75..4bdbc204da 100644
--- a/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
+++ b/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
@@ -30,6 +30,8 @@ The default port is:
* `37743` if in development mode, the port `pnpm desktop:start` runs the desktop app on, so a dev build of the Clipper finds a dev desktop instance.
* `37840` in production, the default Trilium port.
+`pnpm desktop:start-prod` and `desktop:start-prod-no-dir` run the desktop app on `37841`, so a production build of the Clipper needs that port set in its options to find them.
+
## Building
* Run `build` (Chrome) or `build:firefox` to generate the output files, which will be in `.output/[browser]`.
@@ -39,6 +41,23 @@ The sources ZIP has the monorepo's layout: the workspace files and lockfile, `ap
## CI
-`.github/workflows/web-clipper.yml` handles the building of the web clipper. Whenever the web clipper is modified, it generates the ZIPs and uploads them as artifacts.
+`.github/workflows/web-clipper.yml` handles the building of the web clipper. Whenever the web clipper is modified, it generates the ZIPs and uploads them as artifacts. It also rebuilds the Firefox extension from the sources ZIP and fails if the result differs from the regular build, which catches a file missing from `zip.includeSources`.
+
+## Releasing
+
+A release is started by pushing a tag. The version is the one in `apps/web-clipper/package.json`, not the tag's: both stores accept only numbers and dots, and a version can be submitted only once.
+
+* **Release candidate** (`web-clipper-v1.2.0-rc1`, with the version set below the final one, such as `1.1.90`): the Firefox build is signed on Mozilla's unlisted channel, which only signs it and does not list it, and a GitHub pre-release is created with the ZIPs and the signed `.xpi`, which installs in any Firefox.
+* **Release** (`web-clipper-v1.2.0`, with the version set to `1.2.0`): a GitHub release is created with the ZIPs, and the extension is submitted to the Chrome Web Store and to Firefox Add-ons, where it is published once the review passes. Each store is a job of its own, so a failed one can be re-run without submitting to the other again.
+
+Running the workflow by hand (_Actions_ → _Deploy web clipper extension_ → _Run workflow_) checks the store credentials with a dry run, without uploading anything.
+
+The workflow reads these repository secrets:
+
+| Secret | Store | Value |
+| --- | --- | --- |
+| `AMO_JWT_ISSUER`, `AMO_JWT_SECRET` | Firefox Add-ons | API credentials from the Developer Hub (_Tools_ → _Manage API Keys_), of an account that develops the add-on. |
+| `CHROME_PUBLISHER_ID` | Chrome Web Store | The publisher ID shown in the Chrome Web Store developer dashboard. |
+| `CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL`, `CHROME_SERVICE_ACCOUNT_PRIVATE_KEY` | Chrome Web Store | A Google Cloud service account with the Chrome Web Store API enabled, added under _Publisher_ → _Settings_ in the Chrome Web Store developer dashboard. The private key is the PEM block, with real line breaks. |
-There is currently no automatic publishing to the app stores.
\ No newline at end of file
+The release text is not generated; write it on the GitHub release once the workflow has created it.
\ No newline at end of file