ci(preview): publish installable PR builds

.github/workflows/pr-preview-build.yml

@@ -0,0 +1,24 @@
+name: Build CA PR preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Build installable preview
+        run: ./scripts/build-pr-preview.sh "${{ github.event.pull_request.number }}" "${{ github.event.pull_request.head.sha }}"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ca-pr-preview
+          path: dist/pr-preview/
+          if-no-files-found: error
+          retention-days: 7

.github/workflows/pr-preview-cleanup.yml

@@ -0,0 +1,31 @@
+name: Remove CA PR preview
+
+on:
+  pull_request_target:
+    types: [closed]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: ca-pr-preview-publish
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: pr-previews
+      - name: Remove closed PR artifacts
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          test -d "pr/$PR_NUMBER" || exit 0
+          rm -rf "pr/$PR_NUMBER"
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git add -A "pr/$PR_NUMBER"
+          git diff --cached --quiet && exit 0
+          git commit -m "preview: remove closed PR #$PR_NUMBER"
+          git push origin pr-previews

.github/workflows/pr-preview-publish.yml

@@ -0,0 +1,106 @@
+name: Publish CA PR preview
+
+on:
+  workflow_run:
+    workflows: [Build CA PR preview]
+    types: [completed]
+
+permissions:
+  actions: read
+  contents: write
+  issues: write
+  pull-requests: read
+
+concurrency:
+  group: ca-pr-preview-publish
+
+jobs:
+  publish:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: pr-previews
+      - uses: actions/download-artifact@v8
+        with:
+          name: ca-pr-preview
+          path: artifact
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish stable PR installer URL
+        id: publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          PR_NUMBER="$(jq -r '.pr' artifact/preview.json)"
+          ARTIFACT_SHA="$(jq -r '.sha' artifact/preview.json)"
+          [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]
+          test "$ARTIFACT_SHA" = "$HEAD_SHA"
+          echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+
+          PR_STATE="$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json state --jq .state)"
+          if [[ "$PR_STATE" != "OPEN" ]]; then
+            echo "PR #$PR_NUMBER is $PR_STATE; skipping preview publication."
+            echo "published=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "published=true" >> "$GITHUB_OUTPUT"
+          rm -rf "pr/$PR_NUMBER"
+          mkdir -p "pr/$PR_NUMBER"
+          cp -a artifact/. "pr/$PR_NUMBER/"
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git add "pr/$PR_NUMBER"
+          git diff --cached --quiet && exit 0
+          git commit -m "preview: publish PR #$PR_NUMBER at ${HEAD_SHA:0:7}"
+          git push origin pr-previews
+      - name: Add installer link to pull request
+        if: steps.publish.outputs.published == 'true'
+        uses: actions/github-script@v9
+        env:
+          PR_NUMBER: ${{ steps.publish.outputs.pr_number }}
+        with:
+          script: |
+            const issueNumber = Number(process.env.PR_NUMBER)
+            if (!Number.isInteger(issueNumber) || issueNumber < 1) {
+              throw new Error(`Invalid pull request number: ${process.env.PR_NUMBER}`)
+            }
+
+            const marker = '<!-- ca-pr-preview -->'
+            const installerUrl = `https://raw.githubusercontent.com/${context.repo.owner}/${context.repo.repo}/pr-previews/pr/${issueNumber}/community.applications.plg`
+            const body = `${marker}
+            ### Community Applications preview
+
+            Install this PR build on a test server:
+
+            \`${installerUrl}\`
+
+            This is an unreleased test build. The same URL updates when new commits are pushed to this pull request.`
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              ...context.repo,
+              issue_number: issueNumber,
+              per_page: 100
+            })
+            const existing = comments.find(comment =>
+              comment.user?.type === 'Bot' && comment.body?.includes(marker)
+            )
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                ...context.repo,
+                comment_id: existing.id,
+                body
+              })
+            } else {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: issueNumber,
+                body
+              })
+            }

scripts/build-pr-preview.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Build an installable Community Applications preview for a pull request.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PR_NUMBER="${1:?usage: $0 <pr-number> <git-sha> [output-directory]}"
+GIT_SHA="${2:?usage: $0 <pr-number> <git-sha> [output-directory]}"
+OUTPUT_DIR="${3:-$ROOT/dist/pr-preview}"
+SOURCE_DIR="$ROOT/source/community.applications"
+PLUGIN_TEMPLATE="$ROOT/plugins/community.applications.plg"
+SHORT_SHA="${GIT_SHA:0:7}"
+VERSION="$(date -u +%Y.%m.%d)-pr${PR_NUMBER}-${SHORT_SHA}"
+PACKAGE="community.applications-${VERSION}-x86_64-1.txz"
+BASE_URL="https://raw.githubusercontent.com/unraid/community.applications/pr-previews/pr/${PR_NUMBER}"
+
+if [[ ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
+	echo "PR number must be numeric: $PR_NUMBER" >&2
+	exit 1
+fi
+if [[ ! -d "$SOURCE_DIR" || ! -f "$PLUGIN_TEMPLATE" ]]; then
+	echo "Run this script from a complete community.applications checkout." >&2
+	exit 1
+fi
+
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+STAGING="$(mktemp -d -t ca-pr-preview.XXXXXX)"
+trap 'rm -rf "$STAGING"' EXIT
+
+COPYFILE_DISABLE=1 cp -R "$SOURCE_DIR/" "$STAGING/"
+find "$STAGING" \( -name '.DS_Store' -o -name '._*' -o -name 'sftp-config.json' \) -delete
+find "$STAGING" -name '.claude' -type d -prune -exec rm -rf {} + 2>/dev/null || true
+chmod -R 0755 "$STAGING"
+
+if tar --version 2>/dev/null | grep -q 'GNU tar'; then
+	tar -C "$STAGING" --owner=0 --group=0 --numeric-owner -cJf "$OUTPUT_DIR/$PACKAGE" .
+else
+	COPYFILE_DISABLE=1 tar -C "$STAGING" --uid 0 --gid 0 --uname root --gname root -cJf "$OUTPUT_DIR/$PACKAGE" .
+fi
+
+if command -v md5sum >/dev/null 2>&1; then
+	MD5="$(md5sum "$OUTPUT_DIR/$PACKAGE" | awk '{print $1}')"
+else
+	MD5="$(md5 -q "$OUTPUT_DIR/$PACKAGE")"
+fi
+
+python3 - "$PLUGIN_TEMPLATE" "$OUTPUT_DIR/community.applications.plg" "$VERSION" "$MD5" "$BASE_URL/$PACKAGE" "$BASE_URL/community.applications.plg" <<'PY'
+from pathlib import Path
+import re
+import sys
+
+source, destination, version, md5, package_url, plugin_url = sys.argv[1:]
+text = Path(source).read_text(encoding="utf-8")
+replacements = {
+    "version": version,
+    "md5": md5,
+    "pluginURL": plugin_url,
+}
+for entity, value in replacements.items():
+    text, count = re.subn(
+        rf'(<!ENTITY\s+{entity}\s+")[^"]*(">)',
+        rf'\g<1>{value}\g<2>',
+        text,
+        count=1,
+    )
+    if count != 1:
+        raise SystemExit(f"could not replace {entity} entity")
+
+text, count = re.subn(
+    r'(<FILE Name="/boot/config/plugins/&name;/&name;-&version;-x86_64-1\.txz" Run="upgradepkg --install-new --reinstall">\s*<URL>)[^<]*(</URL>)',
+    rf'\g<1>{package_url}\g<2>',
+    text,
+    count=1,
+)
+if count != 1:
+    raise SystemExit("could not replace package URL")
+
+Path(destination).write_text(text, encoding="utf-8")
+PY
+
+cat > "$OUTPUT_DIR/preview.json" <<EOF
+{"pr":${PR_NUMBER},"sha":"${GIT_SHA}","version":"${VERSION}","package":"${PACKAGE}"}
+EOF
+
+echo "Built $OUTPUT_DIR/community.applications.plg"
+echo "Installer: $BASE_URL/community.applications.plg"