Flutter Build

Flutter allows you to build cross-platform apps from a single codebase. This recipe demonstrates how to build iOS, Android, and macOS apps using Flutter, including dependency installation, build compilation, and macOS code signing and distribution.

Flutter iOS Build YAML

name: Flutter iOS Build
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Build iOS
    run: flutter build ios

Flutter Cross-Platform Build

name: Flutter Mobile Build
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Build Android
    run: flutter build apk

  - name: Build iOS
    run: flutter build ios

Build Workflow

The typical Flutter build workflow includes:

1. Dependency Installation: flutter pub get resolves all Pub dependencies specified in pubspec.yaml
2. iOS Build: flutter build ios generates an iOS app bundle
3. Android Build: flutter build apk generates an Android APK

Key Points

Flutter is Pre-Installed on the Build Machine

FVM is pre-installed and manages Flutter SDK installation automatically. Simply set environment.flutter to a version (e.g., 3.24.0), a channel (e.g., stable, beta, master), or fvm to read from .fvmrc, and the agent will install it automatically. Once installed, Flutter and Dart are available directly on PATH — use flutter and dart in your run: commands.

• Correct: flutter pub get, flutter build ios
• Previously: fvm flutter pub get, fvm flutter build ios (no longer required)

• pubspec.yaml: Your Flutter project's manifest file, similar to Package.swift for native Swift or package.json for Node.js
• pub get: Downloads and installs all dependencies from pub.dev
• Platform-specific builds: Flutter can generate both iOS and Android builds from the same source code
• .fvmrc file (optional): Commit this at your repository root to pin the Flutter SDK version; if you set environment.flutter: fvm, the agent will read the version from your .fvmrc file

Building an iOS IPA from Flutter

When auto-signing is fully configured, you can build and export an iOS IPA directly from Flutter:

name: Flutter Build IPA
platform: flutter

environment:
  flutter: "3.41.8"

triggers:
  - push

steps:
  - name: Get dependencies
    run: flutter pub get

  - name: Build iOS
    run: flutter build ios --release --no-codesign

  - name: Create IPA
    run: flutter build ipa --release

Auto-Signing for Flutter IPA Builds

When Apple auto-signing is configured at both the workspace level (API key) and app level (bundle identifier + signing type), RunnerHub automatically passes the generated ExportOptions.plist to your flutter build ipa command via the --export-options-plist flag. You do not need to add this flag manually.

To override with your own provisioning configuration, pass an explicit --export-options-plist=/path/to/your.plist and the agent will not inject (your file takes precedence).

To opt out of signing entirely (for testing purposes), use --no-codesign and the agent will skip injection.

Building a macOS App from Flutter

Flutter can build Mac apps, but a Flutter pipeline always declares platform: flutter — it can never declare platform: macos. To tell RunnerHub that a job produces a Mac app (so it picks macOS provisioning profiles, the Mac Installer certificate, and .pkg deploys), add the target_platform field:

platform: flutter
target_platform: macos

target_platform is optional, works only on Flutter pipelines, and can be set per job in a multi-job pipeline (where it overrides the top-level value).

Before your first macOS build: use a Multi-Platform bundle ID

A macOS job needs an Apple bundle ID registered as MAC_OS or UNIVERSAL. An iOS-only bundle ID will not match, and the build fails with an error like:

Your Apple Developer account already has a bundle ID com.example.myapp registered with platform IOS, which is incompatible with the macOS build. To fix: upgrade the bundle ID to 'Multi-Platform' in Apple Developer (Identifiers → App IDs → select → App ID Type → Multi-Platform), or use a different bundle identifier for your macOS app.

If your Flutter app ships on both iOS and macOS, set the identifier to Multi-Platform (UNIVERSAL) up front and you will never hit this.

Recipe 1 — Mac Development build

The simplest case: build a signed .app for internal testing. flutter build macos writes the app bundle to build/macos/Build/Products/Release/.

name: Flutter macOS Development
platform: flutter
target_platform: macos

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Run tests
    run: flutter test

  - name: Build macOS
    run: flutter build macos --release

artifacts:
  - build/macos/Build/Products/Release/*.app

Set the app's signing type to Development in App Settings → Code Signing.

Recipe 2 — Developer ID (direct distribution outside the Mac App Store)

Developer ID signing produces a .app you can distribute yourself. The build steps are identical to Recipe 1 — only the app's signing type changes.

name: Flutter macOS Developer ID
platform: flutter
target_platform: macos

environment:
  flutter: "3.24.0"

triggers:
  - push

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Build macOS
    run: flutter build macos --release

  # Notarization is NOT automated — run it yourself if you need it.
  - name: Notarize and staple
    run: |
      APP="$(ls -d build/macos/Build/Products/Release/*.app | head -1)"
      ditto -c -k --keepParent "$APP" build/macos/upload.zip
      xcrun notarytool submit build/macos/upload.zip \
        --apple-id "$AC_APPLE_ID" \
        --team-id "$AC_TEAM_ID" \
        --password "$AC_APP_PASSWORD" \
        --wait
      xcrun stapler staple "$APP"

artifacts:
  - build/macos/Build/Products/Release/*.app

Notarization is not automated

RunnerHub does not notarize your app for you — there is no built-in notarization feature for Flutter macOS builds or for native macOS builds. notarytool is available in the build image so you can run it in your own run: step, as shown above. Supply AC_APPLE_ID, AC_TEAM_ID, and an app-specific password (AC_APP_PASSWORD) as environment variables — store the password as a secret so it is masked in logs.

Drop the notarization step entirely if you only need a signed (un-notarized) .app.

With Developer ID, macOS must be your only build output

Signing type is configured on the app, not per job. When an app's signing type is Developer ID, RunnerHub requests Apple signing credentials for every job in the pipeline, and rejects any job that does not target macOS:

Developer ID signing applies only to macOS targets. This job targets flutter. Set target_platform: macos on this job, or change the app's signing type.

This is a fatal error at signing setup — the job fails before your steps run. And it is not limited to iOS: an android or web sibling job fails in exactly the same way, because every non-macOS job reports its platform as flutter, never macos.

So with Developer ID, a Flutter pipeline can build macOS and nothing else. If you also need Android, web, or iOS artifacts from the same repository, choose one of:

• Use Mac App Store signing for the macOS job instead (Recipe 3) — it coexists with other targets.
• Create two RunnerHub apps pointing at the same repository, one per signing type.

Recipe 3 — Mac App Store (.pkg → TestFlight / App Store)

flutter build macos produces a .app bundle and never a .pkg. TestFlight and the App Store only accept a .pkg, so you must archive and export with xcodebuild after the Flutter build.

name: Flutter Mac App Store
platform: flutter
target_platform: macos

environment:
  flutter: "3.24.0"

triggers:
  - event: push
    branches:
      - main

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Build macOS
    run: flutter build macos --release

  - name: Archive
    run: |
      xcodebuild -workspace macos/Runner.xcworkspace \
        -scheme Runner \
        -configuration Release \
        -archivePath build/macos/Runner.xcarchive \
        archive

  - name: Export .pkg
    run: |
      xcodebuild -exportArchive \
        -archivePath build/macos/Runner.xcarchive \
        -exportOptionsPlist "$RH_EXPORT_OPTIONS_PLIST" \
        -exportPath build/macos/export

artifacts:
  - build/macos/export/*.pkg

Set the app's signing type to App Store in App Settings → Code Signing, then add a TestFlight or App Store deploy target.

This recipe requires App Store signing — not Development

The app's signing type decides the export method, and only App Store produces a .pkg. If the app is set to Development, all three steps still run and the job looks healthy, but -exportArchive exports with method: development and no Mac Installer certificate, so it emits a .app — and the build/macos/export/*.pkg glob above matches nothing. You get an empty artifact set instead of a clear error. Confirm the signing type before using this recipe.

Do not declare only *.app with a TestFlight or App Store deploy target

A .app glob is enough for the deploy target to be selected, but the upload itself then looks for a .pkg, finds none, and the job fails — after a full, otherwise successful build.

If you configure a TestFlight or App Store deploy target for a macOS job, you must include the xcodebuild -exportArchive step and declare the .pkg glob:

• Correct: build/macos/export/*.pkg
• Not sufficient on its own: build/macos/Build/Products/Release/*.app

Recipes 1 and 2 declare only *.app on purpose — they have no TestFlight or App Store deploy target.

About RH_EXPORT_OPTIONS_PLIST

RunnerHub generates an ExportOptions.plist inside the build VM whenever Apple signing certificates are installed for the job, and exposes its path as RH_EXPORT_OPTIONS_PLIST.

flutter build macos does not accept an --export-options-plist flag — only flutter build ipa does (and RunnerHub adds it there automatically). For macOS you pass the plist yourself, to xcodebuild -exportArchive, exactly as shown above.

If your repository already contains its own ExportOptions.plist at the workspace root, RunnerHub skips generation and does not set RH_EXPORT_OPTIONS_PLIST — reference your own file by path instead.

Building iOS and macOS in one pipeline

Use a multi-job pipeline and set target_platform per job:

name: Flutter iOS + macOS
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push

jobs:
  ios_build:
    name: Build iOS
    target_platform: ios
    steps:
      - name: Install dependencies
        run: flutter pub get
      - name: Build IPA
        run: flutter build ipa --release
    artifacts:
      - build/ios/ipa/*.ipa

  macos_build:
    name: Build macOS
    target_platform: macos
    steps:
      - name: Install dependencies
        run: flutter pub get
      - name: Build macOS
        run: flutter build macos --release
    artifacts:
      - build/macos/Build/Products/Release/*.app

Both jobs run in parallel because neither declares needs:.

Collecting Flutter Build Artifacts

You can collect build outputs from your Flutter builds:

name: Flutter Build with Artifacts
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push

steps:
  - name: Install dependencies
    run: flutter pub get

  - name: Build iOS
    run: flutter build ios

  - name: Build Android
    run: flutter build apk

artifacts:
  - build/ios/iphoneos/**/*.app
  - build/ios/archive/**/*.xcarchive
  - build/app/outputs/**/*.apk