Build Configuration

There is no build configuration file in Blaze. Each application's settings live on its application page, in cards you open and edit in place, and apply to every deployment of the app.

Build Settings

Open the application page. Under Build infrastructure, open the Build runner card's ··· menu and choose Build settings…. The dialog has these settings:

Only the person who created the app and the workspace's owners and admins can save these settings. Changes apply to the next deployment.

Flutter Channel and Version

• latest on the channel picks the newest release on the channel when each deployment starts, so a new Flutter release changes your next build without you doing anything.
• A specific version makes every deployment use exactly that release, so two deployments of the same commit build with the same Flutter. Pin a version when you want reproducible builds, and change it when you choose to upgrade.

The list only offers releases Blaze knows about. When you pin a version, the deployment stops at Prepare runner if the environment: flutter: constraint in your pubspec.yaml rules that version out, so change one or the other.

Xcode Version

• latest on the runner uses the newest Xcode installed on the macOS runner image.
• A specific version, such as 26.2, uses the newest installed Xcode of that version. If the runner image does not have it, the deployment fails straight away at Clone & pub get, and the message lists the versions the runner does have.

Build Runners

iOS builds run on macOS runners with Apple silicon, and Android builds run on Linux runners. Every plan builds on the Apple M1 and the 2 vCPU x64 runner; Pro and Team add the Apple M4 Pro, about twice as fast, and larger x64 runners. Choose one for each platform in Build settings, which lists every runner with what a minute of it costs in build credit. An app that never chose builds on its plan's default: the M1 on Starter, the 6 vCPU M4 Pro on Pro and Team.

Builds are paid from your workspace's build credit, by the minute, at the price of the runner the build ran on. When a build fails because of Blaze or its runner, its minutes are refunded.

A build may run for 60 minutes on Starter and 120 minutes on Pro and Team, or for the lower limit set in Build settings. A build still running at its limit is stopped.

Branch and Repository

Open the Repository card's ··· menu and choose Branch & repository…:

• Default branch is the branch the deploy dialog and Deploy on push build. The deploy dialog builds the latest commit on it, resolved when the deployment starts.
• Project path is where pubspec.yaml sits in the repository. Leave it empty for an app at the root. See Repository Layout before you change it.
• Deploy on push starts deployments when a push to the default branch changes the app's version. See Deploy on Push for exactly what counts.

Repository Layout

Keep your Flutter app at the root of the repository:

your-flutter-app/
├── android/
├── ios/
├── lib/
│   └── main.dart
└── pubspec.yaml

Apps in a subdirectory, such as a monorepo with the app in apps/mobile, are not supported. Prepare runner reads pubspec.yaml and the platform project files from the Project path, but the build itself always runs at the repository root, so it fails when the app is not there.

What Every Build Does

• Checks out the exact commit being deployed. If that commit no longer exists, for example after a force-push, the deployment fails instead of building a different commit.
• Runs flutter pub get, then builds a release build of lib/main.dart: flutter build ios --release on iOS and flutter build appbundle --release on Android.
• Sets the version from pubspec.yaml and a build number Blaze assigns. See iOS Setup and Android Setup.
• Passes your environment variables to Flutter as --dart-define.
• Signs with the keys on Signing & keys and uploads to the store for the target you chose. See Deployment.
• Reuses caches from earlier deployments: the Flutter SDK and pub packages, Gradle on Android, and CocoaPods, Swift packages and compiled build state on iOS.

What Is Not Supported

• Build modes. Every build is a release build. There are no debug or profile builds.
• Flavors, schemes and entry points. Builds run without --flavor, use the Runner scheme on iOS, and build lib/main.dart.
• Custom build steps. Blaze runs no pre-build or post-build scripts and no code generation. Commit generated files, such as build_runner output, to the repository.
• Extra flutter build arguments, such as --obfuscate or --split-debug-info.
• APK output. Android builds produce App Bundles only.
• A build configuration file. Builds read no configuration file from your repository besides your Flutter project's own files. Every setting on this page lives on the application page.

Troubleshooting

"That Flutter version is not in the release index." Choose a version from the list, or latest on the channel.

"pubspec.yaml requires Flutter … but this project is configured to build with Flutter …" Pin a Flutter version that satisfies environment: flutter: in pubspec.yaml, or change the constraint.

A path: dependency is reported. A dependency that points at an absolute path, a ~/ path or a folder outside the repository does not exist on the build runner. Use a published version or a git dependency.

The build cannot find generated files. Blaze does not run build_runner. Commit the generated files.

Dependencies fail to resolve at Clone & pub get. Run flutter pub get locally with the same Flutter version as your build settings, fix the constraint it reports, and push.

Next Steps

• Environment Variables: values your Dart code reads at build time
• Deployment: start a deployment and follow it
• Flutter build and release documentation