Docs
Build iOS and Android apps on GitHub Actions
No Mac needed on your side and no build service minutes to buy: your own GitHub repository builds the app on its Actions minutes. iOS builds are signed with your App Store Connect key and go to AppForShare for your testers or to TestFlight. Android builds are signed with your upload keystore and go to AppForShare or to a Google Play track. Pro builds up to 2 repositories and Team has no limit (iOS and Android of one repository count once); iOS needs an App Store Connect connection, Google Play needs a Google Play connection.
1. Install the AppForShare Builds app
From Dashboard, Builds, Build on GitHub. You choose the GitHub account or organization and which repositories the app can see. It can open pull requests, set Actions secrets and start workflows; it never pushes to your branches and never merges.
2. Set up a repository
Pick iOS or Android, the repository and the branch to build. For iOS: the App Store Connect key, the bundle ID (the Apple Team ID is filled in when Apple knows it), the .xcworkspace or .xcodeproj, the scheme, where the build goes, how it is signed and how the build number is set. For Android, see the Android section below. AppForShare stores encrypted Actions secrets in the repository and opens a pull request with the workflow file. A repository can have one iOS and one Android setup. When you build a branch other than the default one, a second pull request adds the same file to the default branch, because GitHub only starts a workflow by hand when it is there too; it never runs on a push.
3. Review and merge the pull request
The workflow is a normal file in your repository: .github/workflows/appforshare-ios.yml or appforshare-android.yml. Read it before you merge, and change it later if you need to. AppForShare only starts it and reads its runs.
4. Start builds
Anyone in the workspace with the Developer role or higher starts a build with optional release notes, a channel and a build number. The run uses your repository's GitHub Actions minutes, on a macOS runner for iOS and a Linux runner for Android, or on your own runner (see below). AppForShare shows its progress, the person who started it, the log link and, for builds sent to AppForShare, the new build with its install link, or for Google Play, the version code and track.
Signing
- Xcode's automatic signing with your App Store Connect key makes or updates the provisioning profile. Ad hoc builds include every device registered on your Apple account, so register your testers' devices first (Dashboard, Devices).
- Without a certificate of its own, Xcode asks Apple for a cloud managed distribution certificate, and Apple allows that only for keys with wide access. We recommend adding your distribution certificate as two more secrets instead, so the key keeps a smaller role:
APPFORSHARE_CERT_P12(the .p12 file in base64) andAPPFORSHARE_CERT_PASSWORD. - Or pick "My own Apple Distribution certificate": the workflow sets manual signing on the app target only, so CocoaPods and other targets keep their own settings (one override for every target breaks Pods). Add the two certificate secrets above. Before each build, AppForShare reads the newest App Store (TestFlight) or ad hoc profile of the bundle ID from Apple, or makes one with your valid distribution certificates (and, for ad hoc, every enabled iPhone and iPad), and stores it as the
APPFORSHARE_PROFILEsecret. If the app has push notifications, the build uses the production push environment. Apps with extensions (widgets, notification service) need automatic signing for now. - The key is written to the runner's temporary folder for the build and removed at the end of every run.
Secrets AppForShare sets
APPFORSHARE_TOKEN: an upload token made only for this repositoryAPPFORSHARE_ASC_KEY_ID,APPFORSHARE_ASC_ISSUER_ID,APPFORSHARE_ASC_KEY_P8: your App Store Connect key
GitHub encrypts them and never shows them again, but workflows in the repository, and people who can change workflows, can use them. When you remove the setup, AppForShare deletes the secrets and revokes the token. A client's key connected through an invite link is never copied into a repository.
Build number and version
App Store Connect needs a new, higher build number for each upload. Keep the project's own, or let each run use the date and time (like 2611011430) or the workflow's run number. A number given when you start a build wins. You can also set the version (like 1.4.0); empty keeps the project's.
Android
- Give the folder with gradlew (android for React Native and Flutter, empty for a native app at the root), the app module (app) and the variant, like release or prodRelease when you use flavors. Pick Java 17 or 21 and, for React Native, a Node.js version.
- Signing with your upload keystore: add four secrets in GitHub,
APPFORSHARE_ANDROID_KEYSTORE(the keystore file in base64),APPFORSHARE_ANDROID_KEYSTORE_PASSWORD,APPFORSHARE_ANDROID_KEY_ALIASandAPPFORSHARE_ANDROID_KEY_PASSWORD(for a PKCS12 keystore this is the keystore password). The build signs with them the way Android Studio does, so your Gradle files stay as they are. AppForShare never receives them. Or pick your own Gradle signing if the release build already signs. - To AppForShare: the run builds an .apk and uploads it with the AppForShare GitHub Action, so testers install it from a link.
- To Google Play: the run builds an .aab and uploads it straight to Google Play, into an edit AppForShare opens with your workspace's Google Play connection, then AppForShare checks the bundle and releases it on the track you picked (internal, closed or open testing, or production). The Play key is never copied into the repository, and the bundle never passes through AppForShare. A broken upload carries on from where Google has it. A production release is always left as a draft for you to roll out in Play Console, and an app that was never published only takes drafts. AppForShare never cancels changes that are already in review at Google.
- Version code: the project's own, or the workflow's run number, and a number given when you start a build wins. Google Play needs a new, higher code for every upload. You can also set the version name. Both are set for the build only, without changing your Gradle files.
- AppForShare sets one secret for Android,
APPFORSHARE_ANDROID_TOKEN, an upload token made only for this setup, so an iOS setup on the same repository keeps its own.
# React Native (Gradle folder: android)
npm ci
# React Native in a monorepo (Gradle folder: apps/mobile/android)
cd apps/mobile
npm ci
# Make the keystore secret on your computer
base64 -i upload-keystore.jks | pbcopy # macOS
base64 -w0 upload-keystore.jks # LinuxFor Flutter, use the Flutter preset (below): it sets up Flutter and builds with flutter build apk or appbundle, with the same keystore secrets.
Your own runners (Pro and Team)
- By default a build runs on a GitHub hosted machine: macOS for iOS, Linux for Android. In the setup you can pick My own runner and give its runs-on labels instead, separated by commas, for example
self-hosted, macOS, ARM64for a Mac of your own or the label of your Bitrise Build Hub machine pool, likebitrise-m4-pro. GitHub picks a runner that has every label. Up to 6 labels. - Minutes, the Xcode and Java versions and disk space then depend on that machine, not on GitHub. For iOS it needs macOS with Xcode; leave the Xcode version empty unless the machine has it at /Applications/Xcode_<version>.app. For Android it needs the Android SDK, Java and bash. The workflow skips the steps that free disk space on hosted runners, so nothing on your machine is deleted.
- Keep self hosted runners to private repositories: a pull request from a fork could run code on them. The pull request AppForShare opens says which runner the workflow uses.
When a build fails (Pro and Team)
- When a run fails or runs out of time, AppForShare reads the log of the failed job with the Builds app, keeps the lines around the errors and the end of the log, takes secrets out (keys, tokens, passwords, signed URLs, email addresses) and asks AI for the likely cause and the steps to fix it. The answer shows under the run with its confidence, and the person who started the build gets one email with it.
- Each explanation uses 1 AI action of the workspace. With no actions left, the run says so and you can still press Explain the failure later. In the CLI, --fresh reads the log once more for a new answer.
- The AI only reads. It never changes your code, your workflow file or your repository, and it can be wrong: the full log stays on GitHub.
- From a terminal:
npx appforshare github-runslists runs andnpx appforshare github-runs 42 --explainshows the explanation of run 42. AI tools get the same through the MCP tool github_build_run.
Expo apps without ios and android folders
- When the repository has app.json or an app.config file and eas.json (or the expo package) but no committed ios or android folder, the setup offers the Expo preset. Each run then installs your packages, runs
npx expo prebuild --platform ios --clean(or android) in the app folder and builds the project it makes, on your GitHub Actions minutes. - For iOS the .xcworkspace prebuild made is found by the run, and the scheme is its name unless you give one. For Android the Gradle folder is the android folder of the app. An app in a monorepo folder, like apps/mobile, works the same way.
- Pick an eas.json build profile, like preview, to set its env (with extends and the platform's own env) for the build. Values EAS keeps on Expo's servers, EAS environment variables and secrets, are not in eas.json: add them as GitHub secrets and to the workflow's env.
- Set ios.bundleIdentifier and android.package in the app config; without them prebuild makes names like com.anonymous.app. A repository that commits its own native folder is set up like a React Native app instead, because prebuild --clean would replace that folder.
Flutter apps
- When the repository has a pubspec.yaml with a flutter section and the ios or android folder, the setup offers the Flutter preset. Each run sets up Flutter with subosito/flutter-action and runs
flutter pub getin the app folder, on your GitHub Actions minutes. - The Flutter version comes from .fvmrc, .fvm/fvm_config.json, .flutter-version or an exact environment flutter version in pubspec.yaml. Without one, the run uses the latest stable Flutter; the form says so, and you can type a version like 3.35.7 to build with the same one every time.
- iOS:
flutter build ios --config-only --releasewrites the target file, build name and number and runs pod install, then the run archives ios/Runner.xcworkspace and exports the .ipa with the same signing as any other setup (the App Store Connect key, or your own certificate), ad hoc to AppForShare or to TestFlight. - Android:
flutter build apk --releasefor AppForShare orflutter build appbundle --releasefor Google Play, signed with your upload keystore secrets (passed to Gradle as the android.injected.signing properties, so build.gradle stays as it is) or with the signing in your Gradle files. With the keystore secrets, the alias and passwords cannot contain a comma. - Version and build number from the setup go to Flutter as --build-name and --build-number; without them Flutter uses the version line of pubspec.yaml, like 1.4.0+52. A flavor is passed as --flavor (iOS scheme of that name and the Release-<flavor> configuration, Android variant <flavor>Release) and a target file as -t, like lib/main_dev.dart.
- An app in a monorepo folder, like apps/mobile, works the same way. The workflow file is yours to edit after the merge, for example to add dart-define values.
Build a pull request and comment the install link (Pro and Team)
- When the repository has open pull requests, Build from lets you build the branch of one of them instead of the setup's branch. The workflow file must be on that branch too, so merge the setup's branch into an older pull request first.
- Tick the comment box and, once the build is ready, AppForShare puts its install link, QR code, store readiness result and channel into one comment on the pull request, and updates that comment with each new build, iOS and Android together. The comment is written by the AppForShare Builds app, and the run shows a link to it or why there is none.
- This works for builds sent to AppForShare. TestFlight and Google Play builds have no install link to share. For workflows of your own, the GitHub Action does the same with pr-comment: true (see CI uploads).
React Native and CocoaPods
Add the commands that prepare the iOS project as setup commands, for example:
# React Native
npm ci
cd ios && pod install
# React Native in a monorepo (app in apps/mobile)
cd apps/mobile
npm ci
cd ios && pod installThen point the setup at ios/YourApp.xcworkspace. The .xcworkspace may be made by pod install; it does not need to be in the repository. Pick a Node.js version in the setup for React Native, Expo and Capacitor apps. Flutter apps use the Flutter preset above.