✨ Add Sparkle updater and automated appcast publishing

Robdel12 · Robdel12 · commit 71a5e9cc2bac · 2026-02-12T00:49:36.000-06:00
Wire Sparkle update checks into the menubar app with feed URL fallback and app command integration.\nAdd a GitHub Actions workflow that generates and uploads appcast.xml from release zip assets using Sparkle signing keys.\nDocument one-time setup and release flow for manual signed binaries with automated appcast updates.
diff --git a/.github/workflows/update-appcast.yml b/.github/workflows/update-appcast.yml
@@ -0,0 +1,154 @@
+name: Update Sparkle Appcast
+
+on:
+  release:
+    types: [published, edited]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag (for example: v1.2.3). Leave empty to use latest release."
+        required: false
+        type: string
+      asset_regex:
+        description: "Regex used to find release archives."
+        required: false
+        default: "Vizzly.*\\.zip$"
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  appcast:
+    runs-on: macos-15
+    env:
+      SPARKLE_VERSION: "2.8.1"
+      DEFAULT_ASSET_REGEX: "Vizzly.*\\.zip$"
+    steps:
+      - name: Resolve release and select archive
+        id: resolve
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          INPUT_RELEASE_TAG: ${{ github.event.inputs.release_tag }}
+          INPUT_ASSET_REGEX: ${{ github.event.inputs.asset_regex }}
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_RELEASE_URL: ${{ github.event.release.url }}
+        run: |
+          set -euo pipefail
+
+          asset_regex="${INPUT_ASSET_REGEX:-$DEFAULT_ASSET_REGEX}"
+          if [ -z "$asset_regex" ]; then
+            asset_regex="$DEFAULT_ASSET_REGEX"
+          fi
+
+          if [ "$EVENT_NAME" = "release" ] && [ -n "${EVENT_RELEASE_URL:-}" ]; then
+            release_json="$(gh api "$EVENT_RELEASE_URL")"
+          elif [ -n "${INPUT_RELEASE_TAG:-}" ]; then
+            release_json="$(gh api "repos/$GITHUB_REPOSITORY/releases/tags/$INPUT_RELEASE_TAG")"
+          else
+            release_json="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest")"
+          fi
+
+          tag_name="$(echo "$release_json" | jq -r '.tag_name')"
+          release_id="$(echo "$release_json" | jq -r '.id')"
+
+          archive_name="$(
+            echo "$release_json" \
+              | jq -r --arg re "$asset_regex" '
+                .assets
+                | map(select(.name | test($re)))
+                | sort_by(.updated_at)
+                | last
+                | .name // empty
+              '
+          )"
+
+          if [ -z "$archive_name" ]; then
+            echo "No release asset matched regex: $asset_regex"
+            echo "Upload your signed ZIP first, then rerun this workflow."
+            exit 1
+          fi
+
+          download_url="$(
+            echo "$release_json" \
+              | jq -r --arg name "$archive_name" '.assets[] | select(.name == $name) | .browser_download_url'
+          )"
+
+          if [ -z "$download_url" ]; then
+            echo "Matched asset has no download URL."
+            exit 1
+          fi
+
+          mkdir -p artifacts
+          curl -fL --retry 3 --retry-delay 2 -o "artifacts/$archive_name" "$download_url"
+
+          echo "tag_name=$tag_name" >> "$GITHUB_OUTPUT"
+          echo "release_id=$release_id" >> "$GITHUB_OUTPUT"
+          echo "archive_name=$archive_name" >> "$GITHUB_OUTPUT"
+
+      - name: Install Sparkle tools
+        run: |
+          set -euo pipefail
+          curl -fL --retry 3 --retry-delay 2 \
+            -o sparkle.tar.xz \
+            "https://github.com/sparkle-project/Sparkle/releases/download/$SPARKLE_VERSION/Sparkle-$SPARKLE_VERSION.tar.xz"
+          tar -xJf sparkle.tar.xz
+          generate_appcast_path="$(find . -type f -path "*/bin/generate_appcast" | head -n 1)"
+          if [ -z "$generate_appcast_path" ]; then
+            echo "Could not find generate_appcast in Sparkle distribution."
+            exit 1
+          fi
+          chmod +x "$generate_appcast_path"
+          echo "GENERATE_APPCAST=$generate_appcast_path" >> "$GITHUB_ENV"
+
+      - name: Generate appcast.xml
+        env:
+          SPARKLE_PRIVATE_KEY: ${{ secrets.SPARKLE_PRIVATE_KEY }}
+          TAG_NAME: ${{ steps.resolve.outputs.tag_name }}
+          ARCHIVE_NAME: ${{ steps.resolve.outputs.archive_name }}
+        run: |
+          set -euo pipefail
+          if [ -z "${SPARKLE_PRIVATE_KEY:-}" ]; then
+            echo "Missing SPARKLE_PRIVATE_KEY secret."
+            exit 1
+          fi
+
+          printf "%s" "$SPARKLE_PRIVATE_KEY" > sparkle_private_key
+          chmod 600 sparkle_private_key
+
+          "$GENERATE_APPCAST" \
+            --ed-key-file sparkle_private_key \
+            artifacts
+
+          if [ ! -f artifacts/appcast.xml ]; then
+            echo "generate_appcast did not produce artifacts/appcast.xml"
+            exit 1
+          fi
+
+          python3 - <<'PY'
+from pathlib import Path
+import xml.etree.ElementTree as ET
+import os
+
+appcast_path = Path("artifacts/appcast.xml")
+tree = ET.parse(appcast_path)
+root = tree.getroot()
+
+archive_name = os.environ["ARCHIVE_NAME"]
+tag_name = os.environ["TAG_NAME"]
+repo = os.environ["GITHUB_REPOSITORY"]
+download_url = f"https://github.com/{repo}/releases/download/{tag_name}/{archive_name}"
+
+for enclosure in root.findall(".//enclosure"):
+    enclosure.set("url", download_url)
+
+tree.write(appcast_path, encoding="utf-8", xml_declaration=True)
+PY
+
+      - name: Upload appcast.xml to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG_NAME: ${{ steps.resolve.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          gh release upload "$TAG_NAME" artifacts/appcast.xml --clobber
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ A native macOS menubar app for managing [Vizzly](https://vizzly.dev) TDD servers
 
 ### Direct Download
 
-Download the latest release from [GitHub Releases](https://github.com/vizzly-testing/vizzly-menubar/releases).
+Download the latest release from [GitHub Releases](https://github.com/vizzly-testing/menubar/releases).
 
 ### Homebrew
 
@@ -31,17 +31,42 @@ brew install --cask vizzly
 
 ```bash
 # Clone the repo
-git clone https://github.com/vizzly-testing/vizzly-menubar.git
-cd vizzly-menubar
+git clone https://github.com/vizzly-testing/menubar.git
+cd menubar
 
 # Open in Xcode
-open Vizzly.xcodeproj
+open Vizzly/Vizzly.xcodeproj
 ```
 
 ## How It Works
 
 The menubar app watches `~/.vizzly/servers.json` for running TDD servers and monitors project/log files for live updates. It spawns CLI commands for server lifecycle management.
 
+## Sparkle Updates
+
+Vizzly uses [Sparkle](https://sparkle-project.org/) for in-app updates.
+
+### One-time setup
+
+1. Generate Sparkle keys locally (`generate_keys` from Sparkle tools).
+2. Add `SUPublicEDKey` in the Vizzly app target build settings (Info.plist key).
+3. Add a GitHub Actions secret named `SPARKLE_PRIVATE_KEY` with the full private key contents.
+
+### Release flow (manual binary, automated appcast)
+
+1. Build/sign/notarize `Vizzly.app` locally.
+2. Zip the signed app (for example `Vizzly-1.0.0.zip`).
+3. Create/publish a GitHub release with a tag (for example `v1.0.0`).
+4. Upload the signed `.zip` asset to that release.
+5. GitHub Actions workflow `.github/workflows/update-appcast.yml` will:
+   - find the uploaded zip
+   - generate and sign `appcast.xml`
+   - upload `appcast.xml` to the same release
+
+Sparkle feed URL in the app points to:
+
+`https://github.com/vizzly-testing/menubar/releases/latest/download/appcast.xml`
+
 See [PLAN.md](./PLAN.md) for detailed architecture documentation.
 
 ## License
diff --git a/Vizzly/Vizzly.xcodeproj/project.pbxproj b/Vizzly/Vizzly.xcodeproj/project.pbxproj
@@ -6,6 +6,10 @@
 	objectVersion = 77;
 	objects = {
 
+/* Begin PBXBuildFile section */
+		80BCE4232F3DA45800D91F91 /* Sparkle in Frameworks */ = {isa = PBXBuildFile; productRef = 80BCE4222F3DA45800D91F91 /* Sparkle */; };
+/* End PBXBuildFile section */
+
 /* Begin PBXContainerItemProxy section */
 		80BCD08E2F2994E200D91F91 /* PBXContainerItemProxy */ = {
 			isa = PBXContainerItemProxy;
@@ -52,6 +56,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				80BCE4232F3DA45800D91F91 /* Sparkle in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -112,6 +117,7 @@
 			);
 			name = Vizzly;
 			packageProductDependencies = (
+				80BCE4222F3DA45800D91F91 /* Sparkle */,
 			);
 			productName = Vizzly;
 			productReference = 80BCD0802F2994E100D91F91 /* Vizzly.app */;
@@ -195,6 +201,9 @@
 			);
 			mainGroup = 80BCD0772F2994E100D91F91;
 			minimizedProjectReferenceProxies = 1;
+			packageReferences = (
+				80BCE4212F3DA45800D91F91 /* XCRemoteSwiftPackageReference "Sparkle" */,
+			);
 			preferredProjectObjectVersion = 77;
 			productRefGroup = 80BCD0812F2994E100D91F91 /* Products */;
 			projectDirPath = "";
@@ -403,6 +412,8 @@
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_KEY_LSUIElement = YES;
+				INFOPLIST_KEY_SUPublicEDKey = "UpG9BqC+dujGiVPbWHFVvNu23jlpEqf+EMrv+Dj6cFw=";
+				INFOPLIST_KEY_SUFeedURL = "https://github.com/vizzly-testing/menubar/releases/latest/download/appcast.xml";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
@@ -435,6 +446,8 @@
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_KEY_LSUIElement = YES;
+				INFOPLIST_KEY_SUPublicEDKey = "UpG9BqC+dujGiVPbWHFVvNu23jlpEqf+EMrv+Dj6cFw=";
+				INFOPLIST_KEY_SUFeedURL = "https://github.com/vizzly-testing/menubar/releases/latest/download/appcast.xml";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
@@ -573,6 +586,25 @@
 			defaultConfigurationName = Release;
 		};
 /* End XCConfigurationList section */
+
+/* Begin XCRemoteSwiftPackageReference section */
+		80BCE4212F3DA45800D91F91 /* XCRemoteSwiftPackageReference "Sparkle" */ = {
+			isa = XCRemoteSwiftPackageReference;
+			repositoryURL = "https://github.com/sparkle-project/Sparkle";
+			requirement = {
+				kind = upToNextMajorVersion;
+				minimumVersion = 2.8.1;
+			};
+		};
+/* End XCRemoteSwiftPackageReference section */
+
+/* Begin XCSwiftPackageProductDependency section */
+		80BCE4222F3DA45800D91F91 /* Sparkle */ = {
+			isa = XCSwiftPackageProductDependency;
+			package = 80BCE4212F3DA45800D91F91 /* XCRemoteSwiftPackageReference "Sparkle" */;
+			productName = Sparkle;
+		};
+/* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = 80BCD0782F2994E100D91F91 /* Project object */;
 }
diff --git a/Vizzly/Vizzly/VizzlyApp.swift b/Vizzly/Vizzly/VizzlyApp.swift
@@ -6,6 +6,7 @@
 //
 
 import ServiceManagement
+import Sparkle
 import SwiftUI
 
 // MARK: - Design Tokens
@@ -25,10 +26,11 @@ extension Color {
 @main
 struct VizzlyApp: App {
   @StateObject private var serverManager = ServerManager()
+  private let appUpdater = AppUpdater()
 
   var body: some Scene {
     MenuBarExtra {
-      PanelView(serverManager: serverManager)
+      PanelView(serverManager: serverManager, appUpdater: appUpdater)
     } label: {
       MenuBarLabel(serverManager: serverManager)
     }
@@ -44,6 +46,53 @@ struct VizzlyApp: App {
       }
     }
     .windowResizability(.contentSize)
+    .commands {
+      CommandGroup(after: .appInfo) {
+        Button("Check for Updates…") {
+          appUpdater.checkForUpdates()
+        }
+      }
+    }
+  }
+}
+
+@MainActor
+final class AppUpdater: NSObject {
+  private let updaterController: SPUStandardUpdaterController
+  private let updaterDelegate: FeedURLUpdaterDelegate
+
+  override init() {
+    self.updaterDelegate = FeedURLUpdaterDelegate(
+      fallbackFeedURLString: "https://github.com/vizzly-testing/menubar/releases/latest/download/appcast.xml"
+    )
+    self.updaterController = SPUStandardUpdaterController(
+      startingUpdater: true,
+      updaterDelegate: updaterDelegate,
+      userDriverDelegate: nil
+    )
+    super.init()
+    updaterController.updater.automaticallyChecksForUpdates = false
+  }
+
+  func checkForUpdates() {
+    NSApp.activate(ignoringOtherApps: true)
+    updaterController.checkForUpdates(nil)
+  }
+}
+
+private final class FeedURLUpdaterDelegate: NSObject, SPUUpdaterDelegate {
+  private let fallbackFeedURLString: String
+
+  init(fallbackFeedURLString: String) {
+    self.fallbackFeedURLString = fallbackFeedURLString
+  }
+
+  func feedURLString(for updater: SPUUpdater) -> String? {
+    if let feedURL = Bundle.main.object(forInfoDictionaryKey: "SUFeedURL") as? String,
+       !feedURL.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      return feedURL
+    }
+    return fallbackFeedURLString
   }
 }
 
@@ -86,6 +135,7 @@ struct MenuBarLabel: View {
 
 struct PanelView: View {
   @ObservedObject var serverManager: ServerManager
+  let appUpdater: AppUpdater
   @Environment(\.openSettings) private var openSettings
 
   var body: some View {
@@ -260,6 +310,16 @@ struct PanelView: View {
 
       Spacer()
 
+      Button {
+        appUpdater.checkForUpdates()
+      } label: {
+        Image(systemName: "arrow.down.circle")
+          .font(.system(size: 11, weight: .medium))
+          .frame(width: 28, height: 24)
+      }
+      .buttonStyle(FooterButtonStyle())
+      .help("Check for Updates…")
+
       Button {
         NSApp.activate(ignoringOtherApps: true)
         openSettings()
