In Flutter CI, how do you pin the SDK and reuse the pub cache, and why is pubspec's environment: flutter constraint not a pin?

## Why pinning matters for a Flutter app A Flutter release build depends on the SDK in ways a library dependency does not: the SDK carries the engine, the framework, the Dart compiler and the `flutter` tool that drives Gradle and Xcode. Moving from one stable release to the next can change compile errors, analyzer lints, generated project files and even the iOS migration the tool applies. If the pipeline silently picks up a new SDK, a merge that changed nothing can go red, or worse, ship a binary built with an untested engine. ## Why the pubspec constraint is not a pin ```yaml environment: sdk: ^3.13.0 flutter: '>=3.44.0' ``` The pub documentation says a Flutter SDK constraint is satisfied when pub runs inside the `flutter` executable and the SDK's `version` file meets the constraint's **lower bound**; the Flutter SDK enforces only the lower bound. It protects against building with an SDK that is too old. It says nothing about which newer SDK the pipeline uses. ## Ways to pin | Approach | What it pins | Note | |---|---|---| | setup step with `channel: stable` only | nothing: latest stable that day | common in open-source workflows | | setup step with an exact version | one release | the version lives in the workflow file | | FVM in CI | the version recorded in the project's FVM config | `dart pub global activate fvm`, `fvm install`, `fvm flutter build …` | | `git clone --depth 1 -b 3.47.5` of the SDK | one tag | works on any CI system | | Codemagic `flutter:` setting | a channel, a version or `fvm` | set per workflow | Whichever you choose, make the pipeline print `flutter --version` so every log records the Flutter, Dart and engine versions actually used. ## Reusing the pub cache `flutter pub get` downloads hosted packages into the **system package cache**: `$HOME/.pub-cache` on macOS and Linux, `%LOCALAPPDATA%\Pub\Cache` on Windows, or the directory named by the `PUB_CACHE` environment variable. On an ephemeral CI machine that directory starts empty, so every run downloads every package again. - Persist that directory between runs with the CI system's cache feature, keyed on `pubspec.lock` so a dependency change creates a new entry. - Setup actions such as `subosito/flutter-action` offer a `cache: true` option that enables their own caching. - The job must still work on a cache miss; the cache is an optimisation. - Correctness comes from `pubspec.lock` plus `flutter pub get --enforce-lockfile`, not from the cache. ## Upgrading deliberately 1. Change the pinned version in one pull request, on its own. 2. Let the full pipeline run, including both platform builds, since SDK upgrades often surface in Gradle or Xcode rather than in Dart. 3. Raise the `environment: flutter` lower bound only when the code starts to need the newer SDK, so the constraint keeps meaning something. 4. Keep developers on the same version, for example through the same FVM config, so local and CI results agree. ## Diagnosing a sudden red build When a merge that touched nothing relevant fails, the SDK is the first suspect: 1. Compare the `flutter --version` output of the last green run and the failing one. A different framework revision or Dart version answers the question immediately. 2. If the setup step tracks a channel, the new stable release arrived between the two runs; pin it and schedule the upgrade as its own change. 3. If the SDK is identical, compare `pubspec.lock`; with `--enforce-lockfile` a dependency cannot have moved silently, so look at the cache or the runner image instead. 4. Check the runner image itself: Xcode and the Android SDK are also toolchain inputs, and an image update can break the iOS or Android build while Dart is unchanged. ## Common mistakes - Believing `flutter: '>=3.44.0'` stops CI from using 3.50. - Using `channel: stable` on the setup step and calling it pinned. - Caching the build output folder and restoring stale artefacts into a release build. - Treating a cache hit as proof that dependencies are the ones in the lock file.