Quick Start - Flutter

This guide walks you through setting up a RunnerHub pipeline for Flutter projects. Build, test, and deploy iOS, Android, and macOS from a single codebase.

Prerequisites

Step 1: Create the Pipeline for Flutter iOS

Create .runnerhub/runnerhub.yml in your repository root:

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 --debug

Step 2: Build and Test

Expand your pipeline to include tests and builds:

name: Flutter Build & Test
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

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

  - name: Run tests
    run: flutter test

  - name: Analyze code
    run: flutter analyze

  - name: Build iOS
    run: flutter build ios --debug

Android Build

To build for Android, use the flutter build apk command:

name: Flutter Android Build
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

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

  - name: Build APK
    run: flutter build apk

artifacts:
  - build/app/outputs/**/*.apk

Dual-Platform Build

Build both iOS and Android in a single pipeline:

name: Flutter Mobile Build
platform: flutter

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 iOS
    run: flutter build ios --debug

  - name: Build Android
    run: flutter build apk

artifacts:
  - build/app/outputs/**/*.apk

macOS Build

Flutter can also build Mac apps. Because a Flutter pipeline always declares platform: flutter, you tell RunnerHub that a job targets macOS with the optional target_platform field:

name: Flutter macOS Build
platform: flutter
target_platform: macos

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

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

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

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

In the Pipeline Builder wizard, macOS is one of the selectable build outputs alongside APK, App Bundle, iOS, and Web. When you select it, the wizard asks which macOS distribution you want — Mac App Store, Mac Development, or Developer ID — and generates the matching build steps and artifact globs. Selecting more than one native output produces a multi-job pipeline with one job per target.

Caching

RunnerHub automatically caches Flutter and Dart packages. Dart packages are cached (~/.pub-cache) and restored between builds, keyed on pubspec.lock. CocoaPods and npm caches also apply for the iOS side of Flutter builds. Gradle caches apply for the Android side. The Flutter SDK is cached across builds, so subsequent builds download faster. For faster builds, ensure your pubspec.lock is committed to version control so dependency resolution is deterministic.

Common Commands

Run Flutter tests:

- name: Run tests
  run: flutter test

Code analysis:

- name: Analyze code
  run: flutter analyze

Build iOS release:

- name: Build iOS Release
  run: flutter build ios --release

Build APK:

- name: Build APK
  run: flutter build apk --split-per-abi

Build App Bundle (for Play Store):

- name: Build AAB
  run: flutter build appbundle

Tips

Use Flutter stable channel:

environment:
  flutter: stable

Use Flutter beta channel:

environment:
  flutter: beta

Use environment variables:

steps:
  - name: Build
    run: flutter build ios --debug
    env:
      FLUTTER_ENV: production

What's Next?

iOS Native

Building native iOS? Check out the iOS native guide.

React Native

Using React Native instead? See the React Native guide.

Pipeline Reference

Explore all pipeline options in the YAML reference.

Troubleshooting

Hit a problem? Check the troubleshooting guide.