flutter-action

Flutter environment for use in GitHub Actions. It works on Linux, Windows, and macOS.

The following sections show how to configure this action.

Specifying Flutter version

Use specific version and channel

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: stable
      flutter-version: 3.19.0
  - run: flutter --version

Use version from pubspec.yaml or FVM config

This is inspired by actions/setup-go.

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: stable
      flutter-version-file: pubspec.yaml # path to pubspec.yaml or .fvmrc or .fvm/fvm_config.json
  - run: flutter --version

Important

For flutter-version-file to work, you need to have the exact Flutter version defined in your pubspec.yaml:

Good

environment:
  sdk: ">=3.3.0 <4.0.0"
  flutter: 3.19.0

Bad

environment:
  sdk: ">=3.3.0 <4.0.0"
  flutter: ">= 3.19.0 <4.0.0"

Note

Using flutter-version-file requires yq, which is not pre-installed in windows runners. This action installs yq automatically if flutter-version-file is specified, so no action is required from you.

Use latest release for particular channel

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: stable # or: beta, master (or main)
  - run: flutter --version

Use latest release for particular version and/or channel

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: dev
      flutter-version: 1.22.x
  - run: flutter --version

Use particular version on any channel

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: any
      flutter-version: 3.x
  - run: flutter --version

Use particular git reference on master channel

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: master
      flutter-version: 5b12b74 # tag, commit or branch
  - run: flutter --version

Use a Flutter mirror by set ENV

You can get more infomation from Flutter official docs.

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    env:
      FLUTTER_STORAGE_BASE_URL: https://storage.flutter-io.cn
    uses: step-security/flutter-action@v2
    with:
      channel: master
      flutter-version: 5b12b74 # tag, commit or branch
  - run: flutter --version

Use alternative Flutter repository

This action supports "alternative Flutters" in addition to the official flutter/flutter, for example:

• Flock
• a Flutter fork that supports HarmonyOS

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: master
      flutter-version: 3.24.0
      git-source: https://github.com/join-the-flock/flock.git
  - run: flutter --version

Apply a patch

Sometimes you find a bug in Flutter and fix it yourself (you're a rockstar!), and then submit a patch/PR to Flutter repository. However, everyone knows that code review takes time, but your app needs the fix now.

You can apply your patch like this:

steps:
- name: Clone repository
  uses: actions/checkout@v7
- uses: step-security/flutter-action@v2
  with:
    flutter-version: 3.22.2
    channel: stable
- run: |
    flutter --version
    cd ${{ env.FLUTTER_ROOT }}
    curl https://patch-diff.githubusercontent.com/raw/flutter/flutter/pull/137874.patch | git apply
    git status

Build targets

Build Android APK and app bundle:

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      flutter-version: 3.24.0
  - run: flutter pub get
  - run: flutter test
  - run: flutter build apk
  - run: flutter build appbundle

Build for iOS

Note

Building for iOS requires a macOS runner.

jobs:
  main:
    runs-on: macos-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v7
      - name: Set up Flutter
        uses: step-security/flutter-action@v2
        with:
          channel: stable
      - run: flutter pub get
      - run: flutter test
      - run: flutter build ios --release --no-codesign

Build for the web

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: stable
  - run: flutter pub get
  - run: flutter test
  - run: flutter build web

Build for Windows

jobs:
  main:
    runs-on: windows-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v7
      - name: Set up Flutter
        uses: step-security/flutter-action@v2
        with:
          channel: stable
      - run: flutter build windows

Build for Linux desktop

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v7
      - name: Set up Flutter
        uses: step-security/flutter-action@v2
        with:
          channel: stable
      - run: |
          sudo apt-get update -y
          sudo apt-get install -y ninja-build libgtk-3-dev
      - run: flutter build linux

Build for macOS desktop

Note

Building for macOS requires a macOS runner.

jobs:
  main:
    runs-on: macos-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v7
      - name: Set up Flutter
        uses: step-security/flutter-action@v2
        with:
          channel: stable
      - run: flutter build macos

Caching

Integration with actions/cache:

Important

step-security/flutter-action now uses actions/cache@v5 internally. If you use self-hosted runners, make sure they are updated to Actions Runner 2.327.1 or newer before enabling cache support.

steps:
  - name: Clone repository
    uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    with:
      channel: stable
      cache: true
      # optional parameters follow
      pub-cache: true # optional, defaults to empty (falls back to cache value for backward compatibility)
      cache-key: "flutter-:os:-:channel:-:version:-:arch:-:hash:" # optional, change this to force refresh cache
      cache-path: "${{ runner.tool_cache }}/flutter/:channel:-:version:-:arch:" # optional, change this to specify the cache path
      pub-cache-key: "flutter-pub-:os:-:channel:-:version:-:arch:-:hash:" # optional, change this to force refresh cache of dart pub get dependencies
      pub-cache-path: "${{ runner.tool_cache }}/flutter/:channel:-:version:-:arch:" # optional, change this to specify the cache path
  - run: flutter --version

Note

The cache and pub-cache inputs are independent and control different caches:

• cache: true/false - controls whether to cache the Flutter SDK installation
• pub-cache: true/false - controls whether to cache the pub dependencies

Backward Compatibility: When pub-cache is not specified (empty), it falls back to the cache value. This means existing workflows with cache: true automatically cache both Flutter SDK and pub dependencies.

You can use them in any combination:

• Both enabled: cache: true (pub-cache defaults to true for backward compatibility)
• Both enabled explicitly: cache: true and pub-cache: true
• Only Flutter SDK: cache: true and pub-cache: false
• Only pub dependencies: cache: false and pub-cache: true for self-hosted runners
• Neither: cache: false and pub-cache: false (or omit both)

Note: cache-key, pub-cache-key, and cache-path have support for several dynamic values:

• :os:
• :channel:
• :version:
• :arch:
• :hash:
• :sha256:

Using cache outputs

Note

PUB-CACHE-HIT and CACHE-HIT directly use the cache-hit output from actions/cache@v5, which is the following:

• cache-hit - A string value to indicate an exact match was found for the key.
  • If there's a cache hit, this will be 'true' or 'false' to indicate if there's an exact match for key.
  • If there's a cache miss, this will be an empty string.

Example usage (inspired by actions/cache@v5 to skip melos bootstrap if there was a pub cache hit:

steps:
  - name: Checkout repository
    uses: actions/checkout@v7

  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    id: flutter-action
    with:
      channel: stable
      cache: true

  - name: Conditionally run melos bootstrap
    if: steps.flutter-action.outputs.PUB-CACHE-HIT != 'true'
    run: melos bootstrap

  - name: Continue with build
    run: flutter build apk

Outputs

Use outputs from flutter-action:

steps:
  - name: Clone repository
  - uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    id: flutter-action
    with:
      channel: stable
  - name: Print outputs
    shell: bash
    run: |
      echo CACHE-PATH=${{ steps.flutter-action.outputs.CACHE-PATH }}
      echo CACHE-KEY=${{ steps.flutter-action.outputs.CACHE-KEY }}
      echo CHANNEL=${{ steps.flutter-action.outputs.CHANNEL }}
      echo VERSION=${{ steps.flutter-action.outputs.VERSION }}
      echo ARCHITECTURE=${{ steps.flutter-action.outputs.ARCHITECTURE }}
      echo PUB-CACHE-PATH=${{ steps.flutter-action.outputs.PUB-CACHE-PATH }}
      echo PUB-CACHE-KEY=${{ steps.flutter-action.outputs.PUB-CACHE-KEY }}
      echo CACHE-HIT=${{ steps.flutter-action.outputs.CACHE-HIT }}
      echo PUB-CACHE-HIT=${{ steps.flutter-action.outputs.PUB-CACHE-HIT }}

If you don't need to install Flutter and just want the outputs, you can use the dry-run option:

steps:
  - name: Clone repository
  - uses: actions/checkout@v7
  - name: Set up Flutter
    uses: step-security/flutter-action@v2
    id: flutter-action
    with:
      channel: stable
      dry-run: true
  - run: |
      echo CACHE-PATH=${{ steps.flutter-action.outputs.CACHE-PATH }}
      echo CACHE-KEY=${{ steps.flutter-action.outputs.CACHE-KEY }}
      echo CHANNEL=${{ steps.flutter-action.outputs.CHANNEL }}
      echo VERSION=${{ steps.flutter-action.outputs.VERSION }}
      echo ARCHITECTURE=${{ steps.flutter-action.outputs.ARCHITECTURE }}
      echo PUB-CACHE-PATH=${{ steps.flutter-action.outputs.PUB-CACHE-PATH }}
      echo PUB-CACHE-KEY=${{ steps.flutter-action.outputs.PUB-CACHE-KEY }}
      echo CACHE-HIT=${{ steps.flutter-action.outputs.CACHE-HIT }}
      echo PUB-CACHE-HIT=${{ steps.flutter-action.outputs.PUB-CACHE-HIT }}
    shell: bash