Quick Start - Flutter

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

Note

RunnerHub automatically installs the Flutter SDK based on your environment.flutter setting. 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. Because the Flutter bin directory is not on the VM’s default PATH, invoke Flutter and Dart with the fvm prefix: use fvm flutter and fvm dart in your run: commands. You do not need to manually run fvm install — the agent handles that automatically at job start.

Prerequisites

Note

Before you start, make sure you have:

• A Flutter project with pubspec.yaml
• iOS or Android targets configured
• A RunnerHub account at app.runnerhub.net
• Your Flutter repository connected via GitHub, GitLab, or Bitbucket

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: fvm flutter pub get

  - name: Build iOS
    run: fvm 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: fvm flutter pub get

  - name: Run tests
    run: fvm flutter test

  - name: Analyze code
    run: fvm flutter analyze

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

Android Build

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

name: Flutter Android Build
platform: flutter

environment:
  flutter: "3.24.0"

triggers:
  - push
  - pull_request

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

  - name: Build APK
    run: fvm 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: fvm flutter pub get

  - name: Run tests
    run: fvm flutter test

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

  - name: Build Android
    run: fvm flutter build apk

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

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: fvm flutter test

Code analysis:

- name: Analyze code
  run: fvm flutter analyze

Build iOS release:

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

Build APK:

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

Build App Bundle (for Play Store):

- name: Build AAB
  run: fvm 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: fvm 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.