π OpenHands: AI-Driven Development
feat: add macos build workflow and document the install path (#1911)
Hiep Led8143482639f
diff --git a/.github/workflows/desktop-macos.yml b/.github/workflows/desktop-macos.ymlnew file mode 100644index 0000000000..96d99b6cff--- /dev/null+++ b/.github/workflows/desktop-macos.yml@@ -0,0 +1,91 @@+name: Desktop (macOS)++# Builds the Agent Canvas macOS DMG (Apple Silicon).+# pull_request: paths-filtered smoke build β the uploaded artifact is+# what a tester downloads to verify a PR on macOS.+# release published: rebuilds from the release tag and attaches the .dmg+# to the GitHub Release created by release-please.+# workflow_dispatch: manual escape hatch for any ref.+# The app is only ad-hoc signed (no signing certs exist for any platform);+# a downloaded DMG is quarantined by Gatekeeper, which reports the app as+# "damaged" until the attribute is cleared:+# xattr -d com.apple.quarantine "/Applications/Agent Canvas.app"+# Intel DMGs are not produced β the bundled uv/node runtimes are host-arch+# only, so Intel users build from source.+on:+ workflow_dispatch:+ pull_request:+ paths:+ - .github/workflows/desktop-macos.yml+ - electron/**+ - electron-builder.config.mjs+ - scripts/download-uv.mjs+ - scripts/download-node.mjs+ release:+ types: [published]++concurrency:+ group: desktop-macos-${{ github.ref }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++# `gh release upload` needs contents: write on release events. Fork PR runs+# are downgraded to a read-only token by GitHub automatically.+permissions:+ contents: write++jobs:+ build-dmg:+ name: Build macOS DMG+ runs-on: macos-latest+ timeout-minutes: 30++ steps:+ - name: Check out repository+ uses: actions/checkout@v6++ - name: Set up Node.js with npm cache+ uses: actions/setup-node@v6+ with:+ node-version: '24'+ cache: npm++ - name: Install dependencies+ run: npm ci++ - name: Build macOS DMG+ env:+ # Production analytics key only for release builds (same split as+ # docker.yml); PR/manual runs get the staging key. Both are public+ # client-side keys stored as repo vars β empty on fork PRs, which+ # simply disables analytics in the built app.+ VITE_POSTHOG_API_KEY: ${{ github.event_name == 'release' && vars.POSTHOG_PROD_KEY || vars.POSTHOG_STAGING_KEY }}+ # Authenticates download-uv.mjs's GitHub API version lookup so it+ # doesn't hit the unauthenticated per-IP rate limit on shared runners.+ GITHUB_TOKEN: ${{ github.token }}+ run: npm run build:desktop++ - name: Verify DMG output+ run: |+ ls -la dist-electron+ dmg_count=$(find dist-electron -maxdepth 1 -name '*.dmg' | wc -l | tr -d ' ')+ if [ "$dmg_count" -ne 1 ]; then+ echo "::error::Expected exactly one DMG in dist-electron/, found $dmg_count"+ exit 1+ fi++ - name: Upload DMG artifact+ uses: actions/upload-artifact@v7+ with:+ name: agent-canvas-macos-dmg+ path: dist-electron/*.dmg+ if-no-files-found: error+ # The DMG is large (~175 MB); keep PR artifacts long enough for+ # manual QA without hoarding storage.+ retention-days: 14++ - name: Attach DMG to GitHub release+ if: github.event_name == 'release'+ env:+ GH_TOKEN: ${{ github.token }}+ RELEASE_TAG: ${{ github.event.release.tag_name }}+ run: gh release upload "$RELEASE_TAG" dist-electron/*.dmg --clobberdiff --git a/electron-builder.config.mjs b/electron-builder.config.mjsindex 5131e3ebd5..eb9c11a0e9 100644--- a/electron-builder.config.mjs+++ b/electron-builder.config.mjs@@ -70,6 +70,15 @@ const RUNTIME_PACKAGES = ["sirv", "httpxy"];const repoRoot = dirname(fileURLToPath(import.meta.url));+// Root package.json is the single source of truth for the app version+// (release-please bumps it). electron/package.json is a minimal manifest+// stub pinned at 1.0.0 β `extraMetadata` below overrides its version at+// pack time so artifact names and app.getVersion() carry the released+// version instead.+const rootPackageJson = JSON.parse(+ readFileSync(join(repoRoot, "package.json"), "utf8"),+);+/*** Strip the auto-bundled node_modules from the packaged app, then restore* the small runtime closure of RUNTIME_PACKAGES.@@ -203,6 +212,10 @@ const config = {productName: "Agent Canvas",copyright: "Copyright Β© 2025 All Hands AI",+ // Stamp the packaged app with the released version (see rootPackageJson+ // note above).+ extraMetadata: { version: rootPackageJson.version },+// Treat electron/ as the app root. electron/package.json provides the// Electron entry point without touching the npm-published root package.json.// `buildResources` points at electron/build-resources so electron-builder@@ -274,6 +287,12 @@ const config = {// Or use the dedicated script:// npm run build:desktop:universal//+ // CAUTION: the bundled uv/node extraResources are downloaded for the+ // BUILD HOST's architecture only (scripts/download-uv.mjs and+ // download-node.mjs have no arch override), so a "universal" build still+ // ships single-arch runtimes and breaks on the other architecture. Don't+ // distribute universal DMGs until the download scripts support multi-arch.+ //mac: {category: "public.app-category.developer-tools",target: [@@ -296,6 +315,10 @@ const config = {{ x: 410, y: 220, type: "link", path: "/Applications" },],window: { width: 540, height: 380 },+ // Default is "Agent Canvas-<version>-<arch>.dmg"; GitHub release assets+ // mangle spaces, so keep the asset name literal (matches the nsis+ // convention). ${version}/${arch}/${ext} are electron-builder macros.+ artifactName: "Agent-Canvas-${version}-${arch}.${ext}",},// ββ Windows ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββdiff --git a/scripts/download-uv.mjs b/scripts/download-uv.mjsindex 818c5dd8d2..48b4e114df 100644--- a/scripts/download-uv.mjs+++ b/scripts/download-uv.mjs@@ -73,9 +73,15 @@ async function resolveVersion() {}console.log("[download-uv] Fetching latest uv version from GitHub API...");+ const headers = { "User-Agent": "agent-canvas-build" };+ // Unauthenticated api.github.com calls are rate-limited per IP (60/hour) β+ // shared CI runner IPs exhaust that fast. CI passes GITHUB_TOKEN.+ if (process.env.GITHUB_TOKEN) {+ headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;+ }const data = await fetchJson("https://api.github.com/repos/astral-sh/uv/releases/latest",- { "User-Agent": "agent-canvas-build" }+ headers);const version = data.tag_name?.replace(/^v/, "");if (!version) throw new Error("Could not parse uv version from GitHub API");