One input field, three meanings: flutter-action's flutter-version accepts a release, a wildcard range or a commit hash
Flutter environment for use in GitHub Actions. It works on Linux, Windows, and macOS.
At a glance
- What is it?
- subosito/flutter-action is a composite action, one action.yaml and one setup.sh, that installs a chosen Flutter build on a GitHub runner and caches it. Its documentation is nine variants of the same YAML block and six build targets, and the interesting decisions live in how one version string is overloaded and how much trust the action asks for.
- Who is it for?
- Adopt it if you want Flutter pinned reproducibly across Linux, Windows and macOS runners without maintaining SDK installation in your own scripts, and if you are willing to read which channel value you are passing, because that value decides whether your version string is read as a release, a range or a git reference. Two things deserve a decision before you rely on it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 6 months ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- subosito/flutter-action2,620 ★ · +9
| Repository | 2026-10-04 | 2026-11-15 |
|---|---|---|
| subosito/flutter-action | 2.6k | 2.6k |
9 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The channel value decides how the version string is read
Nine of the README's examples differ only in two input values, and the combinations are the documentation. A specific version on a specific channel uses `channel: stable` with `flutter-version: 3.19.0`. A wildcard range on one channel uses `channel: any` with `flutter-version: 3.x`. A range constrained to a channel uses `channel: dev` with `flutter-version: 1.22.x`. A git reference uses `channel: master` with `flutter-version: 5b12b74`, and the comment on that line says it can be a tag, a commit or a branch. The latest release of a channel needs only `channel: stable` and no version at all. So the same field carries a fixed version, an open range or a git ref, and the channel is what disambiguates them, including the note that the channel itself may be spelled master or main.
The pubspec path only accepts an exact pin, and lists the normal form as wrong
The version-from-file mode points `flutter-version-file` at a pubspec, an FVM config or an FVM JSON config, and the file carries a warning that the exact Flutter version has to be defined there. It shows the acceptable form and the unacceptable one side by side:
environment:
sdk: ">=3.3.0 <4.0.0"
flutter: 3.19.0against a second block where the Flutter line is a range, marked bad. A range is what most pubspec files actually carry for the SDK and usually for Flutter too, so a project that adopted this mode has to convert its constraint into a lock before the action can read it, which changes what the constraint means to every other tool reading the same file. The mode is explicitly modelled on the Go setup action, which has the same exact-pin requirement for the same reason.
The action installs its own copy of yq on runners that lack one
Reading a version out of a YAML or JSON file needs a YAML tool, and the note says `yq` is not pre-installed on Windows runners. The action installs it automatically whenever `flutter-version-file` is specified, so no extra step is required from the user. What the file does not say is which build of `yq` is fetched, from where, or how its integrity is checked before it runs on the runner. On hosted runners this is invisible, because the machine is discarded after the job. On a self-hosted runner the same binary lands on a machine that persists, which is the case where it is worth reading the action's install script before enabling that input.
git-source will install a Flutter from any repository you name
Beyond the official `flutter/flutter`, the action accepts an alternative git source, and two are named: Flock, and a fork on gitee that supports HarmonyOS. The example passes the repository URL alongside a channel and a version:
with:
channel: master
flutter-version: 3.24.0
git-source: https://github.com/join-the-flock/flock.gitSo the SDK your CI compiles against does not have to be the SDK Google publishes, and the example uses a stable-looking version number against the master channel of a fork to do it. Separately, the action honours a storage mirror through an environment variable pointing at the flutter-io.cn host, with a link to the Flutter documentation for that. Between them, a workflow can be pointed at an arbitrary source tree and an arbitrary artifact mirror, and the README describes neither with a verification step.
The patch example mutates the installed SDK inside the job
One documented workflow fetches an upstream pull request as a patch and applies it to the SDK the action just installed:
- run: |
flutter --version
cd ${{ env.FLUTTER_ROOT }}
curl https://patch-diff.githubusercontent.com/raw/flutter/flutter/pull/137874.patch | git apply
git statusThe framing is that you found a Flutter bug, fixed it, submitted the pull request upstream, and cannot wait for review, so your pipeline takes the fix now. The mechanics are worth reading closely: the working directory is the SDK root exposed as an environment variable, the patch arrives over HTTP from a pull request diff host with no checksum and no pinning to a commit, and `git status` is there to show what changed. Whatever else you think of it, it is a supported way to have a build depend on unreviewed upstream code.
Every example pins majors, and the action itself is pinned by major
All nine version examples, all six build examples and the caching example begin with `actions/checkout@v6` and use `subosito/flutter-action@v2`. Both are floating major tags, which means the workflow you copy resolves to whatever those tags point at on the day it runs. Nothing in the file recommends pinning by commit hash, for this action or for the checkout, and no example shows a SHA. There is a runner requirement instead, stated as an important note: the action uses the cache action internally, and self-hosted runners must be on Actions Runner 2.327.1 or newer before cache support is enabled. That is the one supply chain constraint the documentation does state, and it is about the runner rather than about the action.
Build targets need different runners, and one of them skips pub get
Six targets are shown. Android runs `flutter pub get`, `flutter test`, then builds an APK and an app bundle. iOS needs a macOS runner and builds with `--release --no-codesign`, and its example includes the same get and test steps. The web target includes them as well. Windows runs on a Windows runner with a single `flutter build windows` step and no `pub get`. Linux desktop runs on Ubuntu, installs `ninja-build` and `libgtk-3-dev` with apt first, then builds, and again without a get step. macOS needs a macOS runner and builds with one step. So the two examples that skip dependency resolution are the two where the toolchain, rather than the Dart side, is the variable.
The whole action is one YAML file and one shell script
The repository is small and its shape explains the documentation: a `.github/` directory, a licence, the README, `action.yaml`, `setup.sh` and a `test/` directory. So this is a composite action, where the YAML declares inputs and the shell script does the work, rather than a Docker action or a JavaScript one. That choice is why platform differences appear as prose notes rather than as separate implementations, and why the Windows caveat about `yq` is phrased as a fact about the runner image. Attribution is stated up front: originally created by Alif Rachmawadi and maintained by Bartek Pacia. Releases move on a minor cadence, v2.21.0 in June 2025, then v2.22.0 and v2.23.0 eight days apart in March 2026, with the branch last pushed on 2026-04-30.
Editorial conclusion
Adopt it if you want Flutter pinned reproducibly across Linux, Windows and macOS runners without maintaining SDK installation in your own scripts, and if you are willing to read which channel value you are passing, because that value decides whether your version string is read as a release, a range or a git reference. Two things deserve a decision before you rely on it. First, the version-from-file feature only works when your pubspec pins an exact Flutter version, so if yours uses a range you are back to the explicit field. Second, the action will install a fork from any git URL you give it, fetch a binary it does not ship, and reach a mirror you point it at, so treat `git-source`, the mirror environment variable and the patch example as supply chain decisions rather than conveniences, and pin the action by commit in your own workflows even though its examples all use major tags.
Frequently asked questions
How do I pin a Flutter version with subosito/flutter-action?
Use `subosito/flutter-action@v2` with `channel` and `flutter-version`. The README shows a fixed version with a channel, a wildcard range with `channel: any`, a range constrained to a channel, and a git tag, commit or branch with `channel: master`. Omitting `flutter-version` takes the latest release of the channel.
Can flutter-action read the Flutter version from pubspec.yaml?
Yes, through `flutter-version-file`, which accepts a pubspec path, an `.fvmrc` or an `.fvm/fvm_config.json`. It requires an exact Flutter version there, so a range such as `flutter: ">= 3.19.0 <4.0.0"` is listed as unusable. The action installs `yq` itself, which is not pre-installed on Windows runners.
Which platforms can flutter-action build for?
The action works on Linux, Windows and macOS runners. Building for iOS and for macOS requires a macOS runner, the iOS example builds with `--release --no-codesign`, and the Linux desktop example installs `ninja-build` and `libgtk-3-dev` first.
Does subosito/flutter-action cache the Flutter SDK?
It uses `actions/cache@v5` internally. If you run self-hosted runners, the README says to update them to Actions Runner 2.327.1 or newer before enabling cache support.
Can flutter-action install an unofficial Flutter build?
Yes. The `git-source` input accepts alternative repositories, with Flock and a HarmonyOS supporting fork on gitee given as examples, and the action also honours a storage mirror through `FLUTTER_STORAGE_BASE_URL`, shown pointing at the flutter-io.cn host.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/subosito-flutter-action)Star history chart for your README
[](https://hysenlabs.com/projects/subosito-flutter-action)Was this useful?