Split deploy: auto-stage on tag, manual activate via button

build.yml now only stages the binary into ~/hsa-app/releases on tag
(no symlink swap or restart). Activation is a separate workflow_dispatch
workflow (deploy.yml) the user triggers from the Forgejo Actions tab,
passing the tag to point the symlink at and restart. Update INSTALL.md
to describe the stage/activate split.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.forgejo/workflows/build.yml

@@ -16,7 +16,7 @@ jobs:
         with:
           name: hsa
           path: hsa
-      - name: Deploy
+      - name: Stage release
         if: startsWith(github.ref, 'refs/tags/')
         run: |
           echo "${{ secrets.FORGEJO_SSH }}" > /tmp/deploy_key
@@ -26,6 +26,5 @@ jobs:
           TARGET=${{ vars.HSA_APP_USER }}@${{ vars.HSA_APP_HOST }}
           ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no $TARGET "mkdir -p $REL"
           scp -i /tmp/deploy_key -o StrictHostKeyChecking=no hsa $TARGET:$REL/hsa
-          ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no $TARGET \
-            "cd hsa-app && chmod +x releases/hsa-app-V$TAG/hsa && ln -sfn releases/hsa-app-V$TAG/hsa hsa && systemctl --user restart hsa_app"
+          ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no $TARGET "chmod +x $REL/hsa"
           rm /tmp/deploy_key

.forgejo/workflows/deploy.yml

@@ -0,0 +1,24 @@
+name: Deploy
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release version to activate, e.g. 0.0.0a1 (must already be staged in ~/hsa-app/releases/hsa-app-V<tag>/hsa)'
+        required: true
+jobs:
+  deploy:
+    runs-on: shell
+    steps:
+      - name: Activate release
+        run: |
+          echo "${{ secrets.FORGEJO_SSH }}" > /tmp/deploy_key
+          chmod 600 /tmp/deploy_key
+          TAG=${{ github.event.inputs.tag }}
+          TARGET=${{ vars.HSA_APP_USER }}@${{ vars.HSA_APP_HOST }}
+          ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no $TARGET \
+            "cd hsa-app \
+             && test -f releases/hsa-app-V$TAG/hsa \
+             && chmod +x releases/hsa-app-V$TAG/hsa \
+             && ln -sfn releases/hsa-app-V$TAG/hsa hsa \
+             && systemctl --user restart hsa_app"
+          rm /tmp/deploy_key

deploy/INSTALL.md

@@ -1,9 +1,16 @@
 # Deploying hsa-app
 
-The app runs as a **user systemd service** (no sudo). Tagged releases are
-pushed by CI into `~/hsa-app/releases/hsa-app-V<tag>/hsa`, and a `current`
-symlink (`~/hsa-app/hsa`) points at the live release. Restarting the service
-picks up whatever the symlink resolves to.
+The app runs as a **user systemd service** (no sudo). Deployment is two steps:
+
+1. **Stage (automatic on tag)** — pushing a git tag builds + tests, then CI
+   copies the binary into `~/hsa-app/releases/hsa-app-V<tag>/hsa`. Nothing goes
+   live yet.
+2. **Activate (manual button)** — run the **Deploy** workflow from the Forgejo
+   Actions tab ("Run workflow"), entering the tag to activate. It points the
+   `~/hsa-app/hsa` symlink at that release and restarts the service.
+
+The symlink decouples "what's on disk" from "what's running," so activation and
+rollback are just a symlink repoint + restart.
 
 ## Layout on the host
 
@@ -66,7 +73,9 @@ journalctl --user -u hsa_app -f    # follow logs
 
 ## Deploy a tagged release
 
-CI pushes the binary on tag and runs the swap + restart. To do it manually:
+Pushing a tag stages the binary automatically. To activate it, open the repo's
+**Actions → Deploy** workflow, click **Run workflow**, and enter the tag (e.g.
+`0.0.0a1`). To activate from the host instead:
 
 ```bash
 cd ~/hsa-app