DevOps & releases

Flutter environments and flavors: enterprise release setup

A practical guide to Flutter environments, flavors and enterprise release strategies: dev, staging and production, dart-define, branching and CI/CD.

Fabrizio Billeci
Fabrizio Billeci
15 February 2026 · 6 min read
Flutter environments and flavors: enterprise release setup

Introduction

In an enterprise context, a Flutter app must coexist with multiple environments (dev, staging, production), possible variants (flavors for different clients or white-label), and a structured release process. Managing all of this professionally requires clear configuration, conventions and automation.

This article covers environments, flavors, versioning, branching strategies and CI/CD integration for enterprise-level Flutter projects.

Environments vs flavors: differences

First, let us clarify the distinction:

  • Environments: configure where the app points — which API, database, external services. E.g. development, staging, production. Same code, different variables (URLs, API keys, feature flags).
  • Flavor: structural variants of the app — app name, icon, applicationId/bundleId, possibly different features. E.g. free vs paid, white-label for different clients. In Flutter flavors are Android product flavors and iOS schemes.

In practice they are often combined: a staging flavor may point to the staging environment, a production flavor to production. Or flavors per client (clientA, clientB) each with their own environments.

Environments in Flutter

Run modes (Debug / Profile / Release)

Flutter offers three run modes: debug (interpreted, hot reload, debugging), profile (optimized for profiling), release (optimized for production). Do not confuse these with environments: they are compilation modes.

dart-define and dart-define-from-file

To inject environment variables at compile-time:

flutter run --dart-define=API_URL=https://api.dev.example.com
flutter build apk --dart-define=ENV=production --dart-define=API_URL=https://api.example.com

In Dart read them with const String.fromEnvironment('API_URL'). With many variables the command becomes long; use --dart-define-from-file with a JSON file:

// env.production.json
{
  "API_URL": "https://api.example.com",
  "ENV": "production"
}

// build
flutter build apk --dart-define-from-file=env.production.json

Secret handling: env files with API keys must not be committed. Use .gitignore and populate values in CI from a secret store. For maximum security, sensitive keys should be managed server-side, not in the client.

Flavor: Android and iOS configuration

Android (product flavors)

In android/app/build.gradle.kts define flavor dimensions and product flavors:

android {
  flavorDimensions += "env"
  productFlavors {
    create("staging") {
      dimension = "env"
      applicationIdSuffix = ".staging"
      versionNameSuffix = "-staging"
    }
    create("production") {
      dimension = "env"
    }
  }
}

Each flavor has a different applicationId: staging and production can be installed on the same device. For Dart variables per flavor, pass --dart-define at build time.

iOS (schemes and configurations)

iOS has no native flavor concept. Use schemes (e.g. MyApp-Staging, MyApp-Production) and configurations (Debug, Release). Each scheme can have a different bundleId, build variables (Info.plist) and Xcode config. Manual setup takes more steps; tools like flutter_flavorizr help automate.

flutter_flavorizr

Package that generates flavor configuration for Android and iOS from a flavorizr.yaml file. Useful for new projects or standardizing multi-flavor setup. Requires Ruby and Xcodeproj for iOS.

Entry point and bootstrap per environment

For different entry points (e.g. main_dev.dart, main_staging.dart, main_prod.dart) use Flutter targets:

flutter run -t lib/main_staging.dart --flavor staging
flutter build apk -t lib/main_production.dart --flavor production

Or a single main.dart that reads String.fromEnvironment('ENV') and loads the correct config. The separate-file approach is more explicit; the env-var approach is leaner.

Enterprise branching strategies

GitFlow

Classic model for planned releases and multiple versions in production. Uses: main (production-ready), develop (integration), feature/*, release/* (stabilization), hotfix/* (urgent fixes). Ideal for large teams, long release cycles, multiple production versions.

GitHub Flow / Trunk-Based

Simpler: one main branch always deployable, short-lived feature branches merged via PR. Suited for teams releasing often with aggressive CI/CD. Trunk-Based goes further: continuous integration on a single branch, feature flags to hide work in progress.

Suggested conventions

  • Branches: TICKET-123-description or feature/name, fix/name.
  • No direct push to main: always via PR with review and passing CI.
  • main always buildable and tested.
  • Tags for releases: v1.2.3 (semver).

Versioning and build number

Flutter uses version in pubspec.yaml: 1.2.3+45 where 1.2.3 is the version name (visible to users) and 45 the build number (versionCode on Android, CFBundleVersion on iOS). Stores require monotonically increasing build numbers.

In CI you can: use Fastlane with increment_build_number; or scripts that set --build-name and --build-number at build time. The build number can derive from commit count, pipeline ID or a file/secret managed in CI.

CI/CD and pipelines

For enterprise environments the pipeline should:

  • Run tests (unit, widget, integration) on every PR.
  • Build for each required flavor/environment (e.g. staging on merge to develop, production on merge/tag to main).
  • Use secrets for API keys and config; never commit sensitive files.
  • Generate artifacts (APK, AAB, IPA) and publish to stores (manual approval for production) or Firebase App Distribution / TestFlight for staging.
  • Optionally: create tags and automated release notes.

Common tools: GitHub Actions, GitLab CI, Codemagic, Bitrise, Fastlane. Fastlane integrates well with Flutter for build, signing and store upload.

Enterprise setup checklist

  • Distinct environments (dev, staging, prod) with separate URLs and config.
  • Flavors configured on Android and iOS (applicationId/bundleId per environment or client).
  • dart-define or dart-define-from-file for variables; sensitive files in .gitignore.
  • Documented branching strategy; main protected, PRs required.
  • Semantic versioning; build number auto-incremented in CI.
  • CI/CD pipeline with tests, builds per flavor, deploy to staging/prod.
  • Naming conventions and documentation for the team.

Conclusion

A professional setup of environments, flavors and releases in Flutter requires clarity between environments (where the app points) and flavors (which variant is built), correct use of dart-define, Android/iOS configuration and a consistent branching and CI/CD strategy. Investing time in this structure at project start reduces errors, wrong deploys and confusion for the team and in production.

Alongside releases, it is worth tightening token, storage and network security. If you are planning a launch, let's talk.

Fabrizio Billeci
Fabrizio Billeci
Flutter & full-stack app developer · Catania, Italy

Back to the blog

Related articles

Have a project in mind?

Tell me your goals and timeline: I'll get back to you with a concrete proposal, a roadmap and a cost estimate.

Let's talk about your project