feat: update CI and EAS build workflows to use self-hosted macOS runners; enhance documentation for local builds and runner setup

Author: Lalit Sharma

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   ci:
     name: Typecheck · Lint · Test
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, eclipse-timer]
 
     steps:
       - name: Checkout

.github/workflows/eas-build.yml

@@ -1,4 +1,4 @@
-name: EAS Build & Submit
+name: Self-Hosted Mobile Build & Submit
 
 on:
   push:
@@ -25,13 +25,13 @@ on:
         type: boolean
 
 concurrency:
-  group: eas-${{ github.ref }}
+  group: self-hosted-mobile-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
   ci:
     name: CI checks
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, eclipse-timer]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -58,9 +58,9 @@ jobs:
         run: pnpm test
 
   build:
-    name: EAS Build (${{ github.event.inputs.platform || 'all' }})
+    name: Local Build (${{ github.event.inputs.platform || 'all' }})
     needs: ci
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, eclipse-timer]
     env:
       GOOGLE_MAPS_ANDROID_API_KEY: ${{ secrets.GOOGLE_MAPS_ANDROID_API_KEY }}
 
@@ -97,15 +97,60 @@ jobs:
 
       - name: Build
         working-directory: apps/mobile
-        run: eas build --profile production --platform ${{ github.event.inputs.platform || 'all' }} --non-interactive
+        env:
+          EAS_LOCAL_BUILD_ARTIFACTS_DIR: ${{ github.workspace }}/artifacts/raw
+        run: |
+          set -euo pipefail
+          platform="${{ github.event.inputs.platform || 'all' }}"
+
+          if [ "$platform" = "all" ] || [ "$platform" = "ios" ]; then
+            pnpm exec eas build --profile production --platform ios --local --non-interactive
+          fi
+
+          if [ "$platform" = "all" ] || [ "$platform" = "android" ]; then
+            pnpm exec eas build --profile production --platform android --local --non-interactive
+          fi
+
+      - name: Collect build artifacts
+        run: |
+          set -euo pipefail
+          mkdir -p artifacts/submission
+          platform="${{ github.event.inputs.platform || 'all' }}"
+
+          if [ "$platform" = "all" ] || [ "$platform" = "ios" ]; then
+            ios_artifact="$(find artifacts/raw -type f -name '*.ipa' | head -n 1 || true)"
+            if [ -z "$ios_artifact" ]; then
+              echo "Missing iOS artifact (.ipa) in artifacts/raw."
+              exit 1
+            fi
+            cp "$ios_artifact" artifacts/submission/ios.ipa
+          fi
+
+          if [ "$platform" = "all" ] || [ "$platform" = "android" ]; then
+            android_artifact="$(find artifacts/raw -type f -name '*.aab' | head -n 1 || true)"
+            if [ -z "$android_artifact" ]; then
+              echo "Missing Android artifact (.aab) in artifacts/raw."
+              exit 1
+            fi
+            cp "$android_artifact" artifacts/submission/android.aab
+          fi
+
+          ls -lah artifacts/submission
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: local-mobile-builds-${{ github.run_id }}
+          path: artifacts/submission
+          if-no-files-found: error
 
   submit:
     name: Submit to stores
     needs: build
     if: >-
       github.event_name == 'workflow_dispatch' &&
       github.event.inputs.submit == 'true'
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, macOS, eclipse-timer]
     environment: production # Requires manual approval in GitHub settings
 
     steps:
@@ -130,6 +175,31 @@ jobs:
           eas-version: latest
           token: ${{ secrets.EXPO_TOKEN }}
 
-      - name: Submit to App Store Connect & Google Play
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: local-mobile-builds-${{ github.run_id }}
+          path: artifacts/submission
+
+      - name: Submit local artifacts to App Store Connect & Google Play
         working-directory: apps/mobile
-        run: eas submit --platform ${{ github.event.inputs.platform || 'all' }} --non-interactive --latest
+        run: |
+          set -euo pipefail
+          platform="${{ github.event.inputs.platform || 'all' }}"
+          artifact_root="${{ github.workspace }}/artifacts/submission"
+
+          if [ "$platform" = "all" ] || [ "$platform" = "ios" ]; then
+            if [ ! -f "$artifact_root/ios.ipa" ]; then
+              echo "Missing iOS artifact at $artifact_root/ios.ipa."
+              exit 1
+            fi
+            pnpm exec eas submit --platform ios --path "$artifact_root/ios.ipa" --non-interactive
+          fi
+
+          if [ "$platform" = "all" ] || [ "$platform" = "android" ]; then
+            if [ ! -f "$artifact_root/android.aab" ]; then
+              echo "Missing Android artifact at $artifact_root/android.aab."
+              exit 1
+            fi
+            pnpm exec eas submit --platform android --path "$artifact_root/android.aab" --non-interactive
+          fi

README.md

@@ -263,6 +263,8 @@ This repo now reads the key from `GOOGLE_MAPS_ANDROID_API_KEY` at build/config t
    - Value: your Android Maps key
 2. The workflow `.github/workflows/eas-build.yml` injects this secret into the build job.
 3. Android/all builds fail early with a clear message if the secret is missing.
+4. Builds run on a self-hosted macOS runner with label `eclipse-timer`.
+   Runner setup instructions: `documents/self-hosted-macos-runner.md`.
 
 ### Security recommendations
 

documents/README.md

@@ -7,6 +7,7 @@ This folder contains the project documentation for the `eclipse-timer` monorepo.
 ### Planning
 - `documents/01-documentation-plan.md`
 - `documents/release-plan-eas.md`
+- `documents/self-hosted-macos-runner.md`
 
 ### High-Level
 - `documents/high-level/system-overview.md`

documents/release-plan-eas.md

@@ -1,7 +1,7 @@
 # Eclipse Timer — Release Plan (Post v1.0.0)
 
 > Scope: all releases after the first manual Android launch.
-> Goal: use EAS for build, submit, and OTA updates with a repeatable checklist.
+> Goal: use local/self-hosted build, submit, and OTA updates with a repeatable checklist.
 
 ---
 
@@ -12,6 +12,7 @@
 - EAS project ID: `a29a7662-96be-4509-a79e-fbe4b5dac1ff`.
 - Build profile for stores: `production` in `apps/mobile/eas.json` (`autoIncrement: true`).
 - Runtime policy: `runtimeVersion` is tied to app version in `apps/mobile/app.json`.
+- GitHub workflow path for builds is self-hosted macOS (`.github/workflows/eas-build.yml`).
 
 ---
 
@@ -25,6 +26,7 @@
 ## Prerequisites (One-Time)
 
 - `EXPO_TOKEN` is available for CI and local CLI login is valid (`eas whoami`).
+- Self-hosted macOS runner is online with labels `self-hosted`, `macOS`, `eclipse-timer`.
 - Google Play service account is configured for submit in `apps/mobile/eas.json` (or provided via EAS credentials).
 - Store listing metadata is kept current in:
   - `documents/store-metadata.md`
@@ -54,32 +56,34 @@ pnpm lint
 pnpm test
 ```
 
-### 4) Build production binaries with EAS
+### 4) Build production binaries locally
 
 From repo root:
 
 ```bash
-pnpm -C apps/mobile exec eas build --profile production --platform all
+pnpm -C apps/mobile exec eas build --profile production --platform ios --local
+pnpm -C apps/mobile exec eas build --profile production --platform android --local
 ```
 
 Android-only:
 
 ```bash
-pnpm -C apps/mobile exec eas build --profile production --platform android
+pnpm -C apps/mobile exec eas build --profile production --platform android --local
 ```
 
 ### 5) Submit via EAS
 
-Submit latest successful builds:
+Submit local artifacts:
 
 ```bash
-pnpm -C apps/mobile exec eas submit --platform all --latest
+pnpm -C apps/mobile exec eas submit --platform ios --path /absolute/path/to/ios.ipa
+pnpm -C apps/mobile exec eas submit --platform android --path /absolute/path/to/android.aab
 ```
 
 Android-only:
 
 ```bash
-pnpm -C apps/mobile exec eas submit --platform android --latest
+pnpm -C apps/mobile exec eas submit --platform android --path /absolute/path/to/android.aab
 ```
 
 ### 6) Play Console/App Store rollout
@@ -91,6 +95,7 @@ pnpm -C apps/mobile exec eas submit --platform android --latest
 ### 7) Preferred automation path (GitHub Actions)
 
 - Use `.github/workflows/eas-build.yml` for repeatable release execution.
+- Workflow runs on your self-hosted macOS runner.
 - Trigger `workflow_dispatch` with:
   - `platform: android` or `all`
   - `submit: true` when ready to upload automatically after build
@@ -134,7 +139,7 @@ Rules:
 - [ ] Changelog updated
 - [ ] Version updated (`app.json`, `package.json`)
 - [ ] Typecheck/lint/test passed
-- [ ] EAS build completed
+- [ ] Local build completed
 - [ ] EAS submit completed
 - [ ] Release notes entered in store consoles
 - [ ] Rollout started and monitored

documents/self-hosted-macos-runner.md

@@ -0,0 +1,121 @@
+# Self-Hosted macOS Runner Setup (Mac mini)
+
+This project can build both iOS and Android on your own Mac mini using GitHub Actions self-hosted runners.
+The updated workflows run on the label set:
+
+- `self-hosted`
+- `macOS`
+- `eclipse-timer`
+
+Assumption: builds stay local (`eas build --local`) so they do not consume EAS cloud build quota.
+
+## 1. One-time machine prerequisites
+
+Run these on the Mac mini:
+
+```bash
+xcode-select -p
+xcodebuild -version
+```
+
+If needed:
+
+1. Install full Xcode.
+2. Accept license and first-launch setup:
+```bash
+sudo xcodebuild -license accept
+sudo xcodebuild -runFirstLaunch
+```
+
+Android toolchain:
+
+1. Install Android Studio.
+2. Install SDK Platform, Build-Tools, Command-line Tools, and Platform Tools.
+3. Export SDK vars (for the runner user):
+```bash
+echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
+echo 'export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"' >> ~/.zshrc
+echo 'export PATH="$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Node and pnpm:
+
+```bash
+node -v
+corepack enable
+pnpm -v
+```
+
+## 2. Create the self-hosted runner
+
+In GitHub:
+
+1. Open `Settings -> Actions -> Runners -> New self-hosted runner`.
+2. Choose macOS and copy the generated commands.
+3. On the Mac mini, run them in a dedicated folder, for example:
+
+```bash
+mkdir -p ~/actions-runner && cd ~/actions-runner
+# Paste GitHub-provided download/config commands here.
+```
+
+Important while configuring:
+
+1. Runner group: your default or dedicated group.
+2. Labels: include `eclipse-timer` (keep default labels too).
+
+## 3. Install runner as a service
+
+From `~/actions-runner`:
+
+```bash
+./svc.sh install
+./svc.sh start
+./svc.sh status
+```
+
+If your org policy allows it, also set the Mac mini to auto-login and prevent sleep while plugged in for stable CI uptime.
+
+## 4. Repo secrets needed
+
+Set these in `Settings -> Secrets and variables -> Actions`:
+
+1. `EXPO_TOKEN`
+2. `GOOGLE_MAPS_ANDROID_API_KEY`
+
+If you use automated submit:
+
+1. Make sure EAS submit credentials are already configured for Apple and Google Play.
+2. Keep `submit` job gated by the `production` environment approval in GitHub.
+
+## 5. Workflow behavior after this change
+
+- `.github/workflows/ci.yml`: runs typecheck/lint/test on self-hosted macOS runner.
+- `.github/workflows/eas-build.yml`:
+  - Runs CI checks on self-hosted macOS.
+  - Builds locally with:
+    - `eas build --local --platform ios`
+    - `eas build --local --platform android`
+  - Uploads local artifacts (`ios.ipa`, `android.aab`) to the workflow run.
+  - Optional submit job sends those artifacts using `eas submit --path ...`.
+
+## 6. First validation run
+
+1. In GitHub Actions, run `Self-Hosted Mobile Build & Submit`.
+2. Inputs:
+   - `platform: ios` first, then `android`.
+   - `submit: false`.
+3. Confirm build artifacts are attached to the run.
+4. Then run once with `submit: true` when store credentials are confirmed.
+
+## 7. Common issues
+
+1. Runner never picked:
+   - Check runner is online and has label `eclipse-timer`.
+2. iOS signing failures:
+   - Re-check distribution cert/profile setup in your EAS credentials.
+3. Android signing failures:
+   - Re-check keystore credentials in EAS credentials.
+4. Missing Maps key:
+   - Ensure `GOOGLE_MAPS_ANDROID_API_KEY` is present in repository secrets.