Guides

Flutter

Last updated 14 September 2026

Flutter is installed and on the path, with its common packages already in the image. A release iOS build of a new Flutter app finishes in about half a minute.

These numbers are from an actual run on our hardware, not an estimate: a fresh machine was ready in 19 seconds, flutter build ios --release --no-codesign took 31 seconds of which Xcode was 22.5, and the whole build — boot, checkout, project creation, dependencies, compile — billed 79 seconds.

01What is already on the machine

ToolVersion
Flutter3.47.9, stable channel
Dart3.13.7, bundled with Flutter, on the path
Xcode27.2
CocoaPods1.17.0
Android SDKinstalled, with ANDROID_HOME set — you can build both platforms in one run

These are the versions on the default image. To stay on Xcode 26.6 and Flutter 3.44, add one line to your build config — see image.

No flutter doctor ritual, no SDK download step. Your first line can be the build itself.

02The whole file

script:
  - flutter --version
  - flutter pub get
  - flutter build ios --release --no-codesign

artifacts:
  - build/ios/iphoneos/Runner.app

That is a complete, working .macbuildcloud.yml for a Flutter app. It compiles for a real device and gives you back the .app, without any certificate being involved.

--no-codesign is the right default for pull-request builds. Signing is the flakiest part of any iOS pipeline, and there is no reason to make a build that only needs to answer “does this compile?” depend on it. Add signing when you actually want a shippable .ipa.

03Dependencies

The image already holds the packages a typical Flutter project needs, so a build starts with them in place. Anything else comes from pub.dev, the CocoaPods CDN and Maven Central over the public internet. You do not configure any of it.

04Building for Android in the same run

script:
  - flutter pub get
  - flutter build apk --release
  - flutter build ios --release --no-codesign

artifacts:
  - build/app/outputs/flutter-apk/*.apk
  - build/ios/iphoneos/Runner.app

The Android SDK and JDK 17 are installed. Gradle itself comes from your project's own gradlew wrapper, as it should — there is no global Gradle to disagree with the version your project pins. One machine, both platforms, one bill.

05Tests

script:
  - flutter pub get
  - flutter test --machine > test-results.json || true
  - dart run junitreport:tojunit --input test-results.json --output junit.xml

tests:
  - junit.xml

flutter test has no JUnit output of its own, so convert its machine-readable JSON with junitreport. Add it as a dev dependency:

dev_dependencies:
  junitreport: ^2.0.2
The || true matters. Without it, a failing test stops the build before the conversion runs, and you get a red build with no report of which test failed — you would have to read the raw log to find out. With it, the parsed report turns the build red and names the test.

06Producing a signed .ipa

Once your certificate and provisioning profile are stored in Secrets (see code signing & TestFlight):

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore

script:
  - flutter pub get
  - flutter build ipa --release --no-codesign --build-number=$MBC_BUILD_NUMBER
  - xcodebuild -exportArchive \
      -archivePath build/ios/archive/Runner.xcarchive \
      -exportOptionsPlist ios/ExportOptions.plist \
      -exportPath build/ipa

artifacts:
  - build/ipa/*.ipa

Archive without signing, then sign while exporting. That is not a workaround: it is the one arrangement that works for every Flutter project. flutter build ipa can sign on its own only when the Xcode project already names a development team and uses manual signing — a freshly created Flutter project does neither, and we never let Xcode “fix” signing for you, because that creates certificates in your Apple account.

This exact sequence was run on our machines: the exported .ipa passed App Store Connect's own validation with no errors, the Flutter framework inside it re-signed with the same team. The export options plist is described in the signing guide, and uploading to TestFlight is one more line.

07Pinning the Flutter version

The image ships one Flutter version, and we upgrade it deliberately rather than silently. If your project needs a different one, install it in the build:

script:
  - git clone --depth 1 -b 3.35.0 https://github.com/flutter/flutter.git /tmp/f
  - export PATH="/tmp/f/bin:$PATH"
  - flutter --version
  - flutter pub get
  - flutter build ios --release --no-codesign

This costs a minute or two per build because the engine artifacts for that version are not in the image. Worth it if you need it; do not do it out of habit.

08Things that trip people up

SymptomCause
CocoaPods could not find compatible versions A stale ios/Podfile.lock. Either commit a current one, or add cd ios && pod update && cd .. before the build.
Build works locally, fails here on a missing asset The asset is in your .gitignore. The machine only has what is committed — there is no carried-over state from your laptop.
No such module after adding a plugin Run flutter pub get as its own step before the build, not as part of it.
MinimumOSVersion too low when validating or uploading New Flutter projects target iOS 13. App Store Connect refuses anything below iOS 15 from spring 2027. Set IPHONEOS_DEPLOYMENT_TARGET = 15.0 in the Runner target.
Build passes but the artifact is missing The artifacts glob does not match. Add ls -la build/ios/iphoneos/ as the last script line and read the log.

Next: code signing & TestFlight, or the full configuration reference.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.