Merge pull request 'fix(ci): publish the docs with surfer 7, and rebuild release assets on demand' (#382) from fix/ci-surfer-app-password into release/7.20

Reviewed-on: #382

.gitea/workflows/docs.yaml

@@ -0,0 +1,106 @@
+name: Publish code documentation
+run-name: Publishing typedoc and SAS docs
+
+# The code documentation sites are published here rather than inline in the
+# release job, so that they can be republished on their own - after a secret
+# rotation, or for a release whose artefact upload failed (the release job
+# cannot simply be re-run: semantic-release refuses once the tag exists).
+on:
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: '24.5.0'
+
+jobs:
+  typedoc:
+    runs-on: ubuntu-latest
+    # One deploy per site 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-webdoc
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Write .npmrc file
+        run: |
+          echo "$NPMRC" > client/.npmrc
+          echo "legacy-peer-deps=true" >> client/.npmrc
+        shell: bash
+        env:
+          NPMRC: ${{ secrets.NPMRC }}
+
+      - name: Install dependencies
+        run: |
+          cd client
+          # Decrypt and Install sheet
+          echo "$SHEET_PWD" | gpg --batch --yes --passphrase-fd 0 ./libraries/sheet-crypto.tgz.gpg
+          npm ci
+        shell: bash
+        env:
+          SHEET_PWD: ${{ secrets.SHEET_PWD }}
+
+      - name: Build typedoc
+        run: |
+          cd client
+          npm run compodoc:build
+
+      # Deploy tooling is pinned to an exact version: an unpinned `latest` would
+      # let a breaking or compromised upstream release publish straight to the
+      # live site.  `deploy` (v7) replaces the site atomically, and it takes the
+      # Cloudron username plus an app password - the v6 `put --token` flow this
+      # replaces is gone.
+      - name: Deploy typedoc
+        env:
+          SURFER_PASSWORD: ${{ secrets.WEBDOC_DATACONTROLLER_IO }}
+          REF_NAME: ${{ gitea.ref_name }}
+          COMMIT_SHA: ${{ gitea.sha }}
+        run: |
+          set -euo pipefail
+          npx --yes @cloudron/surfer@7.2.0 deploy client/documentation \
+            --server webdoc.datacontroller.io \
+            --username allan \
+            --password "$SURFER_PASSWORD" \
+            --message "Typedoc from ${REF_NAME} @ ${COMMIT_SHA:0:8}"
+
+  sas-docs:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: surfer-code-datacontroller
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: |
+          # `sasjs doc` shells out to doxygen
+          apt-get update
+          apt-get install -y doxygen
+          npm i -g @sasjs/cli
+          cd sas
+          npm i
+
+      - name: Build SAS docs
+        run: |
+          cd sas
+          sasjs doc
+
+      - name: Deploy SAS docs
+        env:
+          SURFER_PASSWORD: ${{ secrets.CODE_DATACONTROLLER_IO }}
+          REF_NAME: ${{ gitea.ref_name }}
+          COMMIT_SHA: ${{ gitea.sha }}
+        run: |
+          set -euo pipefail
+          npx --yes @cloudron/surfer@7.2.0 deploy sas/sasjsbuild/sasdocs \
+            --server code.datacontroller.io \
+            --username allan \
+            --password "$SURFER_PASSWORD" \
+            --message "SAS docs from ${REF_NAME} @ ${COMMIT_SHA:0:8}"

.gitea/workflows/release-assets.yaml

@@ -0,0 +1,195 @@
+name: Release assets
+run-name: Building and uploading the release assets
+
+# Builds the downloadable artefacts for an existing release and uploads them.
+#
+# The release job cuts the tag before it builds, so a failure anywhere between
+# the semantic-release step and the asset upload leaves a published release with
+# no files - and that job cannot simply be re-run, because semantic-release
+# refuses once the tag exists. This workflow rebuilds the artefacts from the tag
+# and attaches them, so the release can be completed without cutting a new one.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and upload (blank = the latest release)'
+        required: false
+        default: ''
+
+env:
+  NODE_VERSION: '24.5.0'
+
+permissions:
+  contents: write
+
+jobs:
+  assets:
+    runs-on: ubuntu-latest
+    # Two runs uploading the same asset names would race the delete-then-upload
+    # below.
+    concurrency:
+      group: release-assets
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Write .npmrc file
+        run: |
+          echo "$NPMRC" > client/.npmrc
+          echo "legacy-peer-deps=true" >> client/.npmrc
+        shell: bash
+        env:
+          NPMRC: ${{ secrets.NPMRC }}
+
+      - name: Resolve the release tag
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          REQUESTED_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          AUTH_HEADER="Authorization: token $GITEA_TOKEN"
+          BASE="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          if [ -n "${REQUESTED_TAG}" ]; then
+            TAG="${REQUESTED_TAG}"
+            # Fail here rather than after a ten-minute build if the tag is not
+            # cut yet or has no release.
+            curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$BASE/releases/tags/${TAG}" > /dev/null
+          else
+            TAG=$(curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$BASE/releases/latest" | jq -r '.tag_name')
+          fi
+          echo "Building assets for ${TAG}"
+          echo "TAG=${TAG}" >> "$GITHUB_ENV"
+
+      - name: Check out the tag
+        run: |
+          set -euo pipefail
+          git fetch --force --tags origin "+refs/tags/${TAG}:refs/tags/${TAG}"
+          git checkout --force "refs/tags/${TAG}"
+
+      - name: Install system packages
+        run: |
+          apt-get update
+          apt-get install -y zip jq
+          npm i -g @sasjs/cli
+
+      - name: Frontend build
+        run: |
+          cd client
+          # Decrypt and Install sheet
+          echo "$SHEET_PWD" | gpg --batch --yes --passphrase-fd 0 ./libraries/sheet-crypto.tgz.gpg
+          npm ci
+          npm i webpack
+          npm run build
+        shell: bash
+        env:
+          SHEET_PWD: ${{ secrets.SHEET_PWD }}
+
+      - name: Build SAS9 EBI Release
+        run: |
+          cd sas
+          npm i
+          sasjs c -t sas9
+          rm -rf sasjsbuild/tests
+          sasjs b -t sas9
+          cp sasjsbuild/mysas9deploy.sas ./demostream_sas9.sas
+          # remove streamed component and rebuild SAS 9 services
+          rm -rf sasjsbuild/services/web9
+          rm sasjsbuild/services/clickme.sas
+          sasjs b -t sas9
+          cp sasjsbuild/mysas9deploy.sas ./sas9.sas
+
+      - name: Build SASjs Server Release
+        run: |
+          cd sas
+          cp sasjs/utils/favicon.ico ../client/dist/favicon.ico
+          sasjs c -t server
+          rm -rf sasjsbuild/tests
+          server_apploc="/Public/app/dc"
+          sed -i "s|apploc=\"[^\"]*\"|apploc=\"${server_apploc}\"|g" sasjsbuild/services/web/index.html
+          sasjs b -t server
+          cp sasjsbuild/server.json.zip ./sasjs_server.json.zip
+
+      - name: Build Viya Release
+        run: |
+          cd sas
+          sasjs c -t viya
+          rm -rf sasjsbuild/tests
+          sed -i -e 's/servertype="SASJS"/servertype="SASVIYA"/g' sasjsbuild/services/DC.html
+          sasjs b -t viya
+          cp sasjsbuild/viya.sas ./viya.sas
+          # compile Viya Full deploy (without web)
+          rm -rf sasjsbuild/services/web
+          rm sasjsbuild/services/DC.html
+          sasjs b -t viya
+          cp sasjsbuild/viya.sas ./viya_noweb.sas
+          cp sasjsbuild/viya.json ./viya_noweb.json
+
+      - name: Zip Frontend (including viya.json for full viya deploy)
+        run: |
+          cd sas
+          cp sasjsbuild/viya.json ../client/dist/viya.json
+          # Zip from *inside* dist so the archive holds the frontend files at its
+          # root rather than under a client/dist/ prefix (see #147).
+          cd ../client/dist
+          zip -r ../../frontend.zip .
+
+      - name: Upload assets to the release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          set -euo pipefail
+          AUTH_HEADER="Authorization: token $GITEA_TOKEN"
+          BASE="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          RELEASE_JSON=$(curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$BASE/releases/tags/${TAG}")
+          RELEASE_ID=$(echo "$RELEASE_JSON" | jq -r '.id')
+          RELEASE_BODY=$(echo "$RELEASE_JSON" | jq -r '.body')
+
+          ASSETS=(frontend.zip
+                  sas/demostream_sas9.sas
+                  sas/viya.sas
+                  sas/sasjs_server.json.zip
+                  sas/sas9.sas
+                  sas/viya_noweb.sas
+                  sas/viya_noweb.json)
+
+          : > SHA256SUMS
+          for f in "${ASSETS[@]}"; do
+            sum=$(sha256sum "$f" | cut -d' ' -f1)
+            printf '%s  %s\n' "$sum" "${f##*/}" >> SHA256SUMS
+          done
+          cat SHA256SUMS
+
+          # Replacing the assets means removing any this workflow uploaded
+          # before, and a second run must not append the verification section
+          # twice.
+          for asset_id in $(echo "$RELEASE_JSON" | jq -r '.assets[]?.id'); do
+            curl -k --fail-with-body -sS -X DELETE -H "$AUTH_HEADER" "$BASE/releases/${RELEASE_ID}/assets/${asset_id}"
+          done
+
+          if echo "$RELEASE_BODY" | grep -q "## Verifying the download"; then
+            echo "Release body already carries the verification section"
+          else
+            VERIFY_SECTION=$(./.gitea/scripts/verify-section.sh)
+            NEW_BODY=$(jq -nr --arg body "$RELEASE_BODY" --arg verify "$VERIFY_SECTION" \
+              '$body + "\n" + $verify + "\n\nFor installation instructions, please visit https://docs.datacontroller.io/"')
+            curl -k --fail-with-body -sS -X PATCH \
+              -H "$AUTH_HEADER" \
+              -H 'Content-Type: application/json' \
+              --data "$(jq -n --arg body "$NEW_BODY" '{draft:false, body:$body}')" \
+              "$BASE/releases/$RELEASE_ID"
+          fi
+
+          URL="$BASE/releases/${RELEASE_ID}/assets"
+          for f in "${ASSETS[@]}"; do
+            echo "Uploading $f ..."
+            curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$URL" -F "attachment=@$f"
+          done
+          echo "Uploading SHA256SUMS ..."
+          curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$URL" -F "attachment=@SHA256SUMS"

.gitea/workflows/release.yaml

@@ -341,19 +341,6 @@ jobs:
           cd ../client/dist
           zip -r ../../frontend.zip .
 
-      - name: Release Typedoc
-        run: |
-          cd client
-          npm -g install cloudron-surfer
-          npm run compodoc:build
-          surfer put --token ${{ secrets.TSDOC_TOKEN }} --server webdoc.datacontroller.io documentation/* /
-
-      - name: Release code.datacontroller.io
-        run: |
-          cd sas
-          sasjs doc
-          surfer put --token ${{ secrets.CODE_DATACONTROLLER_IO }} --server code.datacontroller.io sasjsbuild/sasdocs/* /
-
       - name: Upload assets to release
         env:
           # Use the same ephemeral per-job Gitea Actions token that the
@@ -417,6 +404,33 @@ jobs:
           echo "Uploading SHA256SUMS ..."
           curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$URL" -F "attachment=@SHA256SUMS"
 
+      - name: Publish the code documentation
+        # Typedoc (webdoc) and the SAS docs (code) are published by docs.yaml,
+        # not inline here. Two reasons: the v6 `surfer put --token` flow is gone
+        # in Surfer 7, which takes a Cloudron username plus an app password; and
+        # a dispatch means a stale or failed docs deploy can be republished
+        # without re-running this job, which semantic-release refuses once the
+        # tag exists.
+        #
+        # This runs AFTER the release assets are uploaded: the documentation is
+        # a side channel, and a docs problem must not cost a cut release its
+        # artefacts.
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          set -euo pipefail
+          AUTH_HEADER="Authorization: token $GITEA_TOKEN"
+          BASE="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          TAG=$(curl -k --fail-with-body -sS -H "$AUTH_HEADER" "$BASE/releases/latest" | jq -r '.tag_name')
+          echo "Dispatching code documentation for ${TAG}"
+
+          curl -k --fail-with-body -sS -X POST \
+            -H "$AUTH_HEADER" \
+            -H 'Content-Type: application/json' \
+            --data "$(jq -n --arg ref "refs/tags/$TAG" '{ref: $ref}')" \
+            "$BASE/actions/workflows/docs.yaml/dispatches"
+
       - name: Publish the demo site for this release
         # The tag is created by this job's semantic-release step, so it carries
         # the Actions user as its author - and the forge suppresses ref events