Publishing to the App Store
FlutterGo can build and upload your iOS app to TestFlight or submit it to the App Store, even if you don't own a Mac. With the recommended GitHub Actions method, the build runs on a GitHub-hosted macOS runner in your own repository.
The wizard collects three things from Apple: your Bundle ID, an App Store Connect API key (Key ID, Issuer ID, and the .p8 private key file), and, for cloud builds, a distribution certificate (.p12) used for signing on the runner.
If you prefer building on your own machine, the Native method offers a Build host choice: your local Mac, or an external CI service.
What you need#
- An Apple Developer Program membership ($99/year) and your app record created in App Store Connect with the same Bundle ID.
- An App Store Connect API key: in App Store Connect, then Users and Access, then Integrations, create a key and note the Key ID and Issuer ID, and download the
.p8file (Apple lets you download it only once). - For the GitHub Actions method: an Apple Distribution certificate exported as a
.p12file with its password. - Your project connected (or ready to connect) to GitHub, see Save your code to GitHub.
- Deploy automation is a paid FlutterGo feature.
How to do it#
Step 1, Open the wizard and pick the method#
Click Deploy in the project toolbar. On the Method step choose GitHub Actions (recommended, "Best for iOS without a Mac") or Native (this machine). Then click Continue.
Step 2, Connect GitHub and pick a repository#
Same as the Android path: authorize with Connect GitHub (skipped if already connected), then select an Installed repository or create and Verify a new private one. See Publishing to Google Play for the detailed walkthrough of these two steps.
Step 3, App & release details#
- Platform, pick iOS · TestFlight (or Both for Google Play + TestFlight in one run).
- Release track, TestFlight or App Store (submit for review); see the table below.
- Version (build name) and Build number, e.g.
1.0.0and1; pubspec values are used if left empty. - Release notes / What to test, shown to your TestFlight testers.
Step 4, Enter your Apple credentials#
On the Credentials step (the callout reads: "Need an App Store Connect API key (Key ID, Issuer ID, .p8) and a distribution certificate (.p12) for signing on the runner"):
- Bundle ID, e.g.
com.fluttergo.myapp. Pre-filled from your project; if you change it, FlutterGo writes it back into the project's build files. - ASC Key ID, the Key ID of your App Store Connect API key.
- ASC Issuer ID, the Issuer ID shown at the top of the keys page.
- App Store Connect API key (.p8), upload the
AuthKey_XXXX.p8file. A green check confirms it loaded.
Tip: Credentials are used only for this deployment. In GitHub Actions mode they are stored as encrypted Actions secrets in your repository; in Native mode they are never saved.
Step 5, Signing: distribution certificate (GitHub Actions method)#
Still on Credentials, upload your Distribution certificate (.p12) and enter the .p12 password. The runner imports this certificate to sign the build.
Step 6, Build host (Native method only)#
If you chose Native (this machine), a Build host dropdown appears instead of the certificate fields:
| Build host | What it means |
|---|---|
| Auto (local Mac, else CI) | Uses your Mac if FlutterGo runs on one; otherwise falls back to external CI. |
| Local Mac | Builds the signed .ipa on this machine (requires Xcode set up). |
| External CI | Hands the build to an external CI mac runner, the deploy engine supports Codemagic and GitHub Actions as CI providers. |
Step 7, Review & deploy#
Confirm the summary (Method, Repository, Platform, Track, Version) and click Deploy. In GitHub Actions mode the progress panel shows:
- Push project files to GitHub
- Set encrypted Actions secrets
- GitHub Actions, build & upload to store
Follow the ▶ GitHub Actions run link to watch the macOS runner build the .ipa and upload it to App Store Connect. You can close the wizard with Run in background, progress stays in the toolbar.
Success: "Deployment finished successfully." Your build appears in App Store Connect; TestFlight builds become testable after Apple's automatic processing (usually minutes to an hour).
TestFlight vs App Store#
| TestFlight | App Store (submit for review) | |
|---|---|---|
| Purpose | Beta testing with real users | Public release |
| Who gets it | Testers you invite (internal or via public link) | Everyone on the App Store |
| Review | Light beta review for external testers | Full App Review |
| Reversible? | Yes, stop testing anytime | A released version stays public until you remove the app |
| Recommended first? | Yes, always ship here first | After TestFlight feedback |
Important: App Store (submit for review) sends your app toward a real public release. Submissions and releases are hard to undo, finish your TestFlight rounds first, and keep your store listing (screenshots, description, privacy details) ready in App Store Connect.
Troubleshooting#
Problem: The GitHub Actions build fails on the signing step. Possible causes: Wrong .p12 password; expired distribution certificate; certificate doesn't match the Bundle ID's profile. Solution:
- Open the ▶ GitHub Actions run and read the failed step; the wizard shows the failed step name and log excerpt too.
- Re-export a fresh distribution certificate (
.p12) and re-enter its password. - Click Fix with agent for project-side problems, then Deploy again.
Problem: Upload to App Store Connect is rejected. Possible causes: No app record with this Bundle ID; API key lacks access; build number already used. Solution:
- Create the app in App Store Connect with the exact Bundle ID first.
- Check the API key's role in Users and Access.
- Increase the Build number and deploy again.
Problem: Continue is disabled on the Credentials step. Possible causes: One of Bundle ID, ASC Key ID, ASC Issuer ID, or the .p8 file is missing. Solution:
- Fill all four fields, each file upload shows a green check when loaded.
Problem: Native mode can't build iOS. Possible causes: No local Mac with Xcode; External CI not configured. Solution:
- Switch the Method to GitHub Actions, it needs no Mac.
- Or run FlutterGo on a Mac and pick Local Mac as the build host.
FAQ#
Do I need a Mac to publish an iOS app? No. Choose the GitHub Actions method and the build runs on a GitHub-hosted macOS runner.
How much does Apple charge? The Apple Developer Program is $99 per year. GitHub may charge for macOS runner minutes on private repositories, depending on your GitHub plan.
What exactly is the .p8 file? It's the private key of your App Store Connect API key. Apple lets you download it only once, store it safely. FlutterGo uses it to authenticate the upload; in GitHub Actions mode it is kept as an encrypted repo secret.
TestFlight or App Store first? Always TestFlight first. It's fast, safe, and reversible. Submit to the App Store when your testers are happy.
Can I ship iOS and Android together? Yes, pick Both on the App details step and choose a track for each store; one run ships to both.
Where do I manage testers, screenshots, and the store listing? In App Store Connect. FlutterGo delivers the build; the listing, testers, and review notes stay yours to manage in Apple's console.