Release tested script builds and record deployments

.env-default

@@ -14,3 +14,6 @@ DEV_BROWSER_VERSION=
 DEV_OS=ios
 DEV_DEVICE=
 DEV_OS_VERSION=12
+
+# Command that records GitHub deployments, for example a token broker (defaults to gh)
+DEPLOY_GH_COMMAND=

.github/workflows/browserstack.yml

@@ -3,6 +3,12 @@ name: Browserstack
 on:
   pull_request:
     types: [opened, synchronize, unlabeled]
+  workflow_call:
+    inputs:
+      upload-dist:
+        description: Upload the tested dist files as the "dist" artifact
+        type: boolean
+        default: false
 
 jobs:
   build:
@@ -55,7 +61,7 @@ jobs:
         run: pnpm run test:matrix
 
       - name: Run unit tests
-        run: pnpm run build && pnpm run test:unit && pnpm run test:deploy
+        run: pnpm run test:unit && pnpm run test:deploy
 
       - name: Prettier check (report only, no writes or commits)
         if: always()
@@ -81,6 +87,14 @@ jobs:
           BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
           BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
 
+      - name: Upload tested dist files
+        if: inputs.upload-dist
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
       - name: "Stop BrowserStackLocal"
         if: always() && steps.browserstack.outputs.skip != 'true'
         uses: "browserstack/github-actions/setup-local@master"

.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release
+
+# Bumping VERSION in compile.js on main publishes GitHub Release vN with the
+# BrowserStack-tested build. Deploying it stays a manual `pnpm run deploy`.
+on:
+  push:
+    branches: [main]
+    paths: [compile.js]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  version:
+    # workflow_dispatch can run on any branch, but only main is released
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+      released: ${{ steps.version.outputs.released }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Read the script version
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version=$(sed -n 's/^const VERSION = \([0-9][0-9]*\);$/\1/p' compile.js)
+          if [ -z "$version" ]; then
+            echo "::error file=compile.js::Unable to read const VERSION"
+            exit 1
+          fi
+          tag="v$version"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          # A draft doesn't count (publishing can fail after it's created), and
+          # this read-only token can't see drafts anyway
+          if gh release view "$tag" --repo "$GITHUB_REPOSITORY" --json isDraft \
+              --jq ".isDraft | not" 2> /dev/null | grep -qx true; then
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "$tag is already released; bump VERSION in compile.js to release." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+  test:
+    needs: version
+    if: needs.version.outputs.released != 'true'
+    uses: ./.github/workflows/browserstack.yml
+    with:
+      upload-dist: true
+    secrets: inherit
+
+  publish:
+    needs: [version, test]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish ${{ needs.version.outputs.tag }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.version.outputs.tag }}
+        run: |
+          tar -czf "scripts-$TAG.tar.gz" dist
+          # Reuse the draft of an earlier run whose publish failed
+          if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" > /dev/null 2>&1; then
+            gh release upload "$TAG" "scripts-$TAG.tar.gz" --repo "$GITHUB_REPOSITORY" --clobber
+          else
+            gh release create "$TAG" "scripts-$TAG.tar.gz" \
+              --repo "$GITHUB_REPOSITORY" \
+              --target "$GITHUB_SHA" \
+              --title "$TAG" \
+              --generate-notes \
+              --draft
+          fi
+          gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --target "$GITHUB_SHA" --draft=false --latest

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 *.log
 .env
+/dist

AGENTS.md

@@ -4,7 +4,8 @@ Before working here, read the shared [Simple Analytics instructions](https://git
 
 ## Dist
 
-- `dist/` is generated output. Builds and `pnpm test` rewrite it (each build stamps the date), and a maintainer builds and commits it separately before deploying. Never commit `dist/` changes in feature work; restore it with `git checkout HEAD -- dist` before committing, and skip `dist/` when reviewing or validating changes.
+- `dist/` is gitignored build output. Builds and `pnpm test` write it locally; never commit it.
+- Releases are cut by bumping `VERSION` in `compile.js` on `main`. The Release workflow then builds, tests, and publishes GitHub Release `vN` with `scripts-vN.tar.gz`, which `pnpm run deploy` uploads. Published `vN` SRI files never change.
 
 ## Tracker changes
 

README.md

@@ -28,17 +28,24 @@ Install the pinned Node and pnpm versions, run `pnpm install --frozen-lockfile`,
 
 The most important file of the repository is [`/src/default.js`](src/default.js)
 
-## Deploy
+## Release
+
+Each release is one script version, `vN`. Its SRI file (`sri/vN.js`) never changes after publication, and the `latest` files serve the newest deployed release. `dist/` is build output and is not committed.
 
-Build and commit the distribution files before deploying. The deployment command itself never builds or changes local distribution files.
+1. Open a pull request on `main` that bumps `VERSION` in [`compile.js`](compile.js).
+2. Merging it runs the [Release workflow](.github/workflows/release.yml). It builds the scripts once, runs the unit and BrowserStack tests on those files, and publishes GitHub Release `vN` with `scripts-vN.tar.gz`.
+
+## Deploy
 
 ```sh
 pnpm run deploy
 ```
 
-The interactive CLI starts in dry-run mode by default. It lets you select scripts and destinations, reads the deployed files, and shows every affected path plus the first-line script-header diff. Choosing a real deployment requires a clean repository and a second confirmation.
+The interactive CLI starts in dry-run mode by default. You pick a release (the newest by default), and the CLI downloads its `scripts-vN.tar.gz` and checks the file against the SHA-256 digest GitHub recorded. It then shows the release each destination runs now, every affected path, and the first-line script-header diff. It never builds or reads local `dist/` files. Choosing a real deployment requires a clean repository and a second confirmation. To roll back, deploy an older release; published SRI files are never overwritten.
+
+After a real deployment that includes `latest.js`, the CLI records a GitHub deployment for each destination (`cdn` and `custom-domains`), so [Deployments](https://github.com/simpleanalytics/scripts/deployments) shows what is live. Deployments of only auto-events, SRI or light aren't recorded, because the destination keeps running its recorded release. It runs `gh`, or the command in `DEPLOY_GH_COMMAND`.
 
-CDN writes use `BUNNY_SCRIPTS_ACCESS_KEY` and `BUNNY_SCRIPTS_ACCOUNT_KEY` from `.env`. Custom-domain reads and writes require SSH access to `app@external.simpleanalytics.com`.
+CDN writes use `BUNNY_SCRIPTS_ACCESS_KEY` and `BUNNY_SCRIPTS_ACCOUNT_KEY` from `.env`. Caddy reads and writes require SSH access to `user@esapp05.simpleanalytics.com`.
 
 ## Device testing is sponsored by BrowserStack