Scripts and a macOS Shortcut for building or testing a mobile app (iOS and Android) on a remote Mac. You pick the platform, branch, and options in a few dialogs. The work then runs over SSH on a build Mac, and you get a success or failure alert when it finishes.
The build machine needs no installed copy of these scripts. Each platform has its own local entry point, which streams the matching runner to the remote host over SSH standard input and runs it there with bash -s. The runner is sent as a single block with its standard input redirected from /dev/null, so a command that reads standard input can't consume the rest of the script.
Shortcut (Run Shell Script)
├─ XcodeRemoteBuild.sh <ssh-host> [options] (local, iOS)
│ └─ ssh <host> bash -s -- ... < runner (remote)
│ ├─ XcodeRemoteBuildRemote.sh iOS Fastlane build
│ └─ IOSUnitTestRemote.sh iOS unit tests
└─ AndroidRemoteBuild.sh <ssh-host> [options] (local, Android)
└─ ssh <host> bash -s -- ... < runner (remote)
├─ AndroidRemoteBuildRemote.sh Android Gradle build
└─ AndroidUnitTestRemote.sh Android unit tests
The Android runners share AndroidCommon.sh, which is streamed ahead of them. Run them through AndroidRemoteBuild.sh, not directly.
Each remote runner:
- Resolves the repository at
~/Code/<type>/<repo>, or~/Code/<repo>when--typeis omitted. - Resets and cleans the checkout (
git reset --hard,git clean -ffdx), then fetches the requested branch fromoriginand moves the local branch to the fetched commit, so rebased or force-pushed branches build correctly. - Runs the build or tests.
- Delivers the result: it uploads the build to BrowserStack, publishes it to Google Play, copies it to the build folder, or copies the test report there. The runner has no delivery step for iOS lanes other than
createAppForBrowserStack. - Resets and cleans the checkout again. A trap does this whether the run succeeds or fails.
Each runner reports its result on a SUCCESS: ... or FAILURE: ... line and through its exit status, which decides the Shortcut's alert. Test runners also print a REPORT: line with the report's location, and Play Store builds print a PLAY_STORE_RESULT: line with the publisher's response.
If the result was delivered but the final reset failed, the runner prints a WARNING: ... line instead and exits with status 3. The entry point passes that status on, so a run that already published or uploaded a build isn't mistaken for a failed one and repeated. The next run resets the checkout again before it starts.
Warning: Every run discards uncommitted changes and untracked or ignored files in the remote checkout. Use a checkout on the build Mac that is dedicated to these builds.
| File | Runs on | Purpose |
|---|---|---|
XcodeRemoteBuild.sh |
Local Mac | iOS entry point. Validates arguments, picks the iOS runner, and runs it on the SSH host. |
AndroidRemoteBuild.sh |
Local Mac | Android entry point. Validates arguments, picks the Android runner, and runs it on the SSH host. |
LocalCommon.sh |
Local Mac | Code shared by the two entry points: loading config.sh, streaming the runner, and reporting its exit status. |
XcodeRemoteBuildRemote.sh |
Remote Mac | iOS build: pod install, Bundler, then a Fastlane lane. Can upload the IPA to BrowserStack. |
IOSUnitTestRemote.sh |
Remote Mac | iOS unit tests through fastlane ios test. Copies the HTML reports to the build folder. |
AndroidRemoteBuildRemote.sh |
Remote Mac | Android build with the Gradle wrapper. Produces an APK or AAB. |
AndroidUnitTestRemote.sh |
Remote Mac | Android unit tests with the Gradle wrapper. Copies the HTML reports to the build folder. |
AndroidCommon.sh |
Remote Mac | Code shared by the Android runners: Java and SDK lookup, local.properties handling, checkout, and cleanup. |
Shortcut/Type-RunShellScript.sh |
Local Mac | Script body for the Shortcut's Run Shell Script action. Collects options through dialogs and shows the result. |
config.example.sh |
Local Mac | Template for config.sh, which holds your machine-specific settings. See Configuration. |
./XcodeRemoteBuild.sh <ssh-host> --repo <repository-name> --branch <branch> [options] # iOS
./AndroidRemoteBuild.sh <ssh-host> --repo <repository-name> --branch <branch> [options] # Android| Option | Applies to | Description |
|---|---|---|
--type <name> |
All | Subdirectory under ~/Code on the remote Mac, such as work or personal. |
--repo <name> |
All | Repository directory name. Required. |
--branch <branch> |
All | Branch to check out. Required. |
--shortCode <code> |
Builds, Android tests | App short code. iOS passes it to Fastlane as name:<code>. Android uses it as the Gradle flavor. Required for builds and Android unit tests. |
--lane <lane> |
iOS build | Fastlane lane to run. Required for iOS builds. |
--newApple |
iOS build | Use the "new" Fastlane environment. The default is "old". |
--features <text> |
Builds | iOS: extra Fastlane options, such as featureFlags:BROWSERSTACK apiDev:true. Android: space-separated Gradle properties without -P. |
--buildType <type> |
Android build | Release, Debug, BrowserStack, or Play Store. Required for Android builds. |
--buildPackage <type> |
Android build | APK or Bundle (AAB). Required for Android builds. |
--bundleId <id> |
Android Play Store | Android application ID to publish. Required with --buildType 'Play Store'; the package must be Bundle. |
--devApis <true|false> |
Android BrowserStack | Sets -PAPI_DEV_ENABLED. Defaults to false. |
--unitTests |
Tests | Run unit tests instead of a build. |
--devices <Latest|All> |
iOS tests | Optional device selection passed to the test lane. |
-h, --help |
All | Show the help text. |
iOS BrowserStack build:
./XcodeRemoteBuild.sh ios-build-mac --type work --repo ios-app \
--branch feature/CM-123-Example --lane createAppForBrowserStack \
--shortCode MyApp --features "apiDev:true"iOS unit tests on the latest simulators:
./XcodeRemoteBuild.sh ios-build-mac --unitTests --type work --repo ios-app \
--branch develop --devices LatestAndroid release bundle:
./AndroidRemoteBuild.sh android-build-mac --type work \
--repo android-app --branch develop \
--buildType Release --buildPackage Bundle --shortCode MyFlavorAndroid unit tests:
./AndroidRemoteBuild.sh android-build-mac --unitTests --type work \
--repo android-app --branch develop --shortCode MyFlavor- Requires Xcode at
/Applications/Xcode.app, plus CocoaPods and Bundler on the remote Mac. - Adds Homebrew, rbenv, and asdf shim directories to
PATHand forces a UTF-8 locale. A non-interactive SSH session doesn't get the user's shell profile. - Loads Fastlane credentials and settings by calling the zsh function named in
RMB_FASTLANE_SELECTORfrom the remote~/.zshrc. The runner imports only the variables it needs and doesn't print them. - Runs
bundle installonly whenbundle checkfails. - Disables Fastlane's
terminal-notifierdesktop notification for the run. Its bundled binary is Intel-only and fails on Apple Silicon. - For the
createAppForBrowserStacklane, renames the IPA in<repo>/$RMB_IOS_IPA_DIR/to<ticket>-<shortCode>.ipaand uploads it to BrowserStack App Live. The folder must contain exactly one IPA. - When Fastlane fails, prints a short summary after cleanup so the cause appears in the Shortcut's 12-line alert. The summary names the failed Fastlane action, followed by the most specific
[!]or Xcode error lines.
- Fetches the branch from
originand resets the local branch to match it. - Always selects the "old" Fastlane environment.
--newApplehas no effect on test runs. - Sets
DEVELOPER_DIRto the full Xcode installation sosimctlis available. - Runs
bundle exec fastlane ios testwith standard input redirected from/dev/null. This stops test tools from consuming the rest of the streamed script. - Copies the whole
fastlane/test_outputfolder toRMB_BUILDS_DIR/iOS/<timestamp>/<branch>/, which keeps the links fromreport.htmlto each device's report working. It then checks that the number of HTML files matches and thatreport.htmlisn't empty. - If tests fail but a report exists, the report is delivered and the run still ends with
SUCCESS: Tests Ran. The test failures are recorded in the report. If the run stops before the normal copy step, the cleanup trap tries to copy the report first. - If there's no report, the run fails and prints a short failure summary after cleanup.
- Builds the Gradle project in
<repo>/$RMB_ANDROID_PROJECT_DIR. - Preserves the ignored
local.propertiesfile across both cleans so machine-local settings such asKEYSTORE_DIRremain available for this build and later runs. The copy is kept in~/.remote-mobile-builds/<type>/<repo>/, readable only by your user, and is deleted once restored. If a run is interrupted or can't restore the file, for example because the branch has no Android project, the next run for that repository restores it automatically. - Checks for the Android project after checking out the branch, so a branch without it fails that run but doesn't block later runs.
- Selects Java 17 or 21. It tries
JAVA_HOME, then/usr/libexec/java_home, then the JBR bundled with Android Studio, then Homebrew, jenv, and SDKMAN installs. - Finds the Android SDK through
ANDROID_HOME, thenANDROID_SDK_ROOT, then~/Library/Android/sdk. - Runs
assemble<shortCode><buildType>for APKs orbundle<shortCode><buildType>for AABs.BrowserStackbuilds runassemble<shortCode>Debug -Pbrowserstack=trueand always produce an APK, whatever--buildPackagesays. Play Store builds runbundle<shortCode>Release. - When Gradle fails, prints its
What went wrongblock after cleanup so the cause appears in the Shortcut's 12-line alert. - Picks the newest artifact under
app/build/outputswhose path contains the short code, and renames it to<ticket>-<shortCode>.<apk|aab>. - Uploads
BrowserStackbuilds to BrowserStack, publishes Play Store bundles to the production track withtools/play_release.py, and copies other builds to the build folder. The Shortcut alert includes the publisher result. - Play Store builds require
tools/play_release.pyon the selected Android-app branch and a service-account key path configured throughRMB_ANDROID_PLAY_SERVICE_ACCOUNT_JSON; the key itself remains on the Android build Mac.
- Runs
./gradlew test<shortCode>DebugUnitTestin<repo>/$RMB_ANDROID_PROJECT_DIR. - Finds Java and the Android SDK the same way as Android builds.
- Copies
app/build/reports/tests/test<shortCode>DebugUnitTesttoRMB_BUILDS_DIR/Android/<timestamp>/<branch>/. It then checks that the number of HTML files matches and thatindex.htmlisn't empty. - If tests fail but a report exists, the report is delivered and the run still ends with
SUCCESS: Tests Ran. The test failures are recorded in the report. - If there's no report, the run fails and prints a short failure summary after cleanup.
- Preserves
local.propertiesacross both cleans, the same way as Android builds.
When a branch name contains a CM- Jira key such as CM-1234, the key is the ticket part of the file name. Otherwise, iOS and Android both use the last path segment of the branch, so feature/login becomes login.
Machine-specific settings, such as host names, folders, repository names and your email address, are kept in config.sh, not in the scripts. config.sh is listed in .gitignore, so it stays on your machine. To create it:
cp config.example.sh config.shThen edit the values:
| Setting | Used by | Description |
|---|---|---|
RMB_BUILDS_HOST |
Remote runners | SSH host that receives finished builds and test reports. |
RMB_BUILDS_DIR |
Remote runners | Absolute folder on that host where builds and reports are saved. |
RMB_FASTLANE_SELECTOR |
iOS runners | zsh function in the build Mac's ~/.zshrc that exports the Fastlane environment. It is called as <function> --version <old|new> --xcode /Applications/Xcode.app --gdriveemail <email>. |
RMB_GDRIVE_EMAIL |
iOS runners | Google Drive account passed to that function. |
RMB_IOS_IPA_DIR |
iOS build runner | Folder inside the iOS repository where the BrowserStack lane writes its IPA. |
RMB_ANDROID_PROJECT_DIR |
Android runners | Folder inside the Android repository that contains the Gradle project. |
RMB_ANDROID_PLAY_SERVICE_ACCOUNT_JSON |
Android Play Store builds | Absolute path on the Android build Mac to the Play Developer API service-account JSON key. |
RMB_IOS_HOST, RMB_ANDROID_HOST |
Shortcut | SSH hosts that run iOS and Android jobs. |
RMB_REPO_TYPE |
Shortcut | Subdirectory under ~/Code on the build Macs. Leave it empty if there is none. |
RMB_IOS_REPO, RMB_ANDROID_REPO |
Shortcut | Repository directory names on the build Macs. |
RMB_IOS_SHORTCODE_DEFAULT, RMB_ANDROID_SHORTCODE_DEFAULT |
Shortcut | Default short codes shown in the Shortcut's dialogs. |
PUSH_P12, P12_PASSWORD |
Shortcut (optional) | Certificate and password for result push notifications sent with desktoppush. |
Both entry points load config.sh from their own folder. Each run requires only the settings its runner uses, so an Android-only setup can leave the iOS settings empty:
| Run | Required settings |
|---|---|
| iOS build | RMB_FASTLANE_SELECTOR, RMB_GDRIVE_EMAIL, RMB_IOS_IPA_DIR |
| iOS unit tests | RMB_BUILDS_HOST, RMB_BUILDS_DIR, RMB_FASTLANE_SELECTOR, RMB_GDRIVE_EMAIL |
| Android build or unit tests | RMB_BUILDS_HOST, RMB_BUILDS_DIR, RMB_ANDROID_PROJECT_DIR |
The entry point adds export lines for those settings to the start of the script it streams over SSH. AndroidRemoteBuild.sh also exports the Play service-account key path as GOOGLE_PLAY_SERVICE_ACCOUNT_JSON when configured. Play Store builds stop with an error if that path is empty. The remote runners also check that those settings are present.
- Clone this repository and create
config.shas described in Configuration. - Configure key-based SSH access to the build hosts in
~/.ssh/config. - Create a Shortcut with a single Run Shell Script action (shell:
bash) and paste in the contents ofShortcut/Type-RunShellScript.sh. The script expects the repository at~/Code/personal/RemoteMobileBuilds. If you cloned it somewhere else, changeRMB_DIRat the top of the script.
- Checkouts of the repositories under
~/Code/<type>/. - iOS: Xcode, CocoaPods, Bundler, and the Fastlane selector function (
RMB_FASTLANE_SELECTOR) in~/.zshrc. - Android: a JDK 17 or 21, the Android SDK, and an executable
gradlewin<repo>/$RMB_ANDROID_PROJECT_DIR/. - Play Store builds:
python3, plus the service-account key at the path inRMB_ANDROID_PLAY_SERVICE_ACCOUNT_JSON. - BrowserStack uploads: a file at
~/Code/BrowserStackAuthcontainingusername:access_key. - Delivery to the build folder: SSH access from the build Mac to
RMB_BUILDS_HOST. Android builds are copied toRMB_BUILDS_DIR, which must already exist. iOS test reports go toRMB_BUILDS_DIR/iOS/<timestamp>/<branch>/(openreport.html), and Android test reports go toRMB_BUILDS_DIR/Android/<timestamp>/<branch>/(openindex.html).
iOS signing often needs the remote login Keychain unlocked. To unlock it, set XCODE_REMOTE_KEYCHAIN_PASSWORD in the local environment before running XcodeRemoteBuild.sh. The password is sent as the first line of the SSH standard input. It never appears in the SSH command line or in process arguments. The runner unsets it after the unlock, so Fastlane and other child processes never see it. Only iOS builds use the password. XcodeRemoteBuild.sh doesn't send it for test runs, even if it's set, and AndroidRemoteBuild.sh never sends it.
The Shortcut reads this password from the local login Keychain, so it is never stored in the script. Store it once in Terminal; -w at the end makes security prompt for the password:
security add-generic-password -a "$USER" -s XcodeRemoteBuildKeychain -wTo change it later, add -U to update the existing item. If the item is missing, iOS builds from the Shortcut stop with an alert. The first time the Shortcut reads the item, macOS may ask you to allow access; choose Always Allow.
When you run it, the Shortcut asks for:
- The platform: iOS or Android.
- Whether to run unit tests. iOS tests then ask for the devices and the branch. Android tests ask for the short code and the branch.
- For iOS builds: the Apple account (Old or New), the branch, the lane (
createAppForBrowserStack,updateAppForStore, orcreateLaunchImages), the short code, the Dev APIs setting (createAppForBrowserStackonly), and optional feature flags. Choosingtruefor Dev APIs addsapiDev:trueto the feature flags. - For Android builds: the branch, the build type, the package type, the Dev APIs setting (BrowserStack builds only), the short code, and optional Gradle feature flags. Play Store builds require Bundle, then ask for a Bundle ID defaulting to
com.goeshow.<shortCode>and publish the completed release bundle to production.
On success, it shows the runner's SUCCESS: line; Play Store builds also show the publisher result. Unit-test runs show a fixed message that points to the timestamped Builds folder. That alert means the tests finished and the report was delivered, not that they passed, so check the report. The exact location is on the REPORT: line in the script's output. If the result was delivered but the remote reset failed (exit status 3), it shows a warning alert with the WARNING: line and any REPORT: or publisher result. Don't run the job again in that case. On failure, it shows a critical alert with the lane or build type, the branch, and the last 12 lines of output.
If desktoppush is installed, the Shortcut also sends a push notification as each result alert opens. The title is Remote Build, the subtitle is the platform, and the body is the alert's message followed by its title (Success, Failure, or Delivered, but Cleanup Failed). The Shortcut looks for desktoppush on its PATH and in ~/.local/bin, /opt/homebrew/bin, and /usr/local/bin. Set PUSH_P12 and P12_PASSWORD in config.sh. If desktoppush is missing or fails, the Shortcut behaves as before.