Merge pull request 'ci(publish): deploy the docs site with surfer 7 and an app password' (#25) from ci/surfer-app-password into main

Reviewed-on: #25

.gitea/workflows/publish.yml

@@ -3,6 +3,13 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
+
+# One deploy at a time: `surfer deploy` swaps the site atomically, so two runs
+# racing is not corruption, but it is a wasted build and the last swap wins.
+concurrency:
+  group: surfer-docs
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -19,7 +26,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.12'  # Specify your desired version (e.g., 3.10 or 3.12)
+          python-version: '3.12'  # Specify your desired version (e.g. 3.10 or 3.12)
         env:
           AGENT_TOOLSDIRECTORY: /opt/hostedtoolcache
           RUNNER_TOOL_CACHE: /opt/hostedtoolcache
@@ -31,13 +38,6 @@ jobs:
           apt install -y ./google-chrome*.deb;
           export CHROME_BIN=/usr/bin/google-chrome
 
-      # Deploy tooling is pinned to exact versions: the workflow builds whatever
-      # is committed, and an unpinned `latest` would let a breaking or
-      # compromised upstream release ship straight to the live site.
-      - name: Install Surfer
-        run: |
-          npm -g install cloudron-surfer@6.4.1
-
       - name: build site
         run: |
           pip install mkdocs==1.6.1
@@ -48,5 +48,29 @@ jobs:
           mkdir site/slides
           npx @marp-team/marp-cli@4.5.1 slides/innovation/innovation.md -o ./site/slides/innovation/index.html
           npx @marp-team/marp-cli@4.5.1 slides/if/if.md -o site/if.pdf --allow-local-files --html=true
+
+      # Deploy tooling is pinned to exact versions: the workflow builds whatever
+      # is committed, and an unpinned `latest` would let a breaking or
+      # compromised upstream release ship straight to the live site.
+      #
+      # `deploy` (v7) replaces the site atomically - it extracts to a staging
+      # folder and swaps it in, so a failed upload leaves the current site
+      # serving.  The v6 `put` this replaces was token authenticated, and v7
+      # takes the Cloudron username plus an app password instead.
+      #
+      # The docs live in a NAMED site, `docs`, served at its own alias domain -
+      # not the app's default site - so the name and the domain are both passed.
       - name: Deploy docs
-        run: surfer put --token ${{ secrets.SURFERKEY }} --server docs.datacontroller.io site/* /
+        env:
+          SURFER_PASSWORD: ${{ secrets.SURFER_PASSWORD }}
+          REF_NAME: ${{ gitea.ref_name }}
+          COMMIT_SHA: ${{ gitea.sha }}
+        run: |
+          set -euo pipefail
+          npx --yes @cloudron/surfer@7.2.0 deploy site \
+            --server docs.datacontroller.io \
+            --username allan \
+            --password "$SURFER_PASSWORD" \
+            --site-name docs \
+            --domain docs.datacontroller.io \
+            --message "Build from ${REF_NAME} @ ${COMMIT_SHA:0:8}"