This guide explains the difference in plain English, walks through how to decide, and points out the mistakes founders commonly make when they get this call wrong.

Quick Answer

Cross-platform development (using tools like Flutter or React Native) lets you build one codebase that runs on both iOS and Android, which is usually faster and cheaper to build and maintain. Native development means writing separate apps in Swift/SwiftUI for iOS and Kotlin/Jetpack Compose for Android, which typically costs more but gives you the best possible performance, the fastest access to new OS features, and the smoothest platform-specific feel. Most early-stage startups start cross-platform and only move to native when a specific, provable need arises.

What’s Actually Different, in Plain English

“Native” means the app is written directly in the language and tools each phone maker provides — Swift (and the SwiftUI framework) for Apple devices, and Kotlin (with Jetpack Compose) for Android. Because the code talks directly to the operating system, native apps tend to feel the most polished, launch the fastest, and get first access to new hardware or OS features like camera upgrades or widgets.

“Cross-platform” means writing the app once in a shared language — Dart for Flutter, or JavaScript/TypeScript for React Native — and having that single codebase compile down to both iOS and Android. Modern cross-platform tools have closed most of the performance gap: Flutter renders its own UI with Google’s Impeller graphics engine, and React Native’s newer architecture removed the old performance bottleneck (the “bridge”) between JavaScript and native code. For the vast majority of business apps — booking tools, marketplaces, content apps, internal tools — users won’t notice a meaningful difference in day-to-day performance.

There’s also a middle path worth knowing about: Kotlin Multiplatform (KMP) lets teams share business logic across platforms while still writing native UI on each side, which some teams use to get native feel with less duplicated logic.

How to Decide: Key Factors for Founders

Budget and timeline: building two native apps means paying for two specialized teams (an iOS developer and an Android developer) working in parallel, or building one platform first and porting later. Cross-platform lets one team ship to both platforms from a single codebase, which is usually the faster and cheaper route to a testable product — a real consideration if you’re trying to validate an idea before raising more money.

Team and hiring: React Native draws from the huge pool of JavaScript/web developers, which can make hiring or contracting easier and cheaper. Flutter has a smaller but fast-growing developer pool. Native development requires specialists in Swift and Kotlin separately, who tend to command higher rates and are harder to find on a tight timeline.

Performance and platform depth: if your app is graphics-intensive (games, AR, heavy animation), does deep hardware integration (camera processing, Bluetooth accessories, background audio), or needs to be first to support brand-new OS features, native gives you more direct control and fewer workarounds. For most CRUD-style, content, or transactional apps, this rarely matters.

Long-term plans: if you know you’ll eventually need best-in-class performance or platform-specific UI on both iOS and Android, some teams choose native from day one to avoid a costly rewrite later. But many successful apps launched cross-platform and never needed to switch — the code quality of your team usually matters more than the framework.

Tips / Common Mistakes

Don’t choose native “just in case” without a concrete reason — it roughly doubles your ongoing engineering cost (two codebases to build, test, and maintain) and slows down every feature release, since every change has to be built twice.

Don’t assume cross-platform means low quality — apps built with Flutter and React Native power many well-known, high-traffic consumer apps today. The framework is rarely the reason an app feels cheap; inconsistent design and rushed UX usually are.

Do prototype with your actual use case before committing. If your app leans heavily on animation, camera, or background processing, build a small proof-of-concept in your candidate framework before signing a full development contract.

Do ask any agency or freelancer why they’re recommending a specific framework for your app, not just their default. A good answer references your actual requirements — budget, timeline, platform priority, and technical complexity — not just “this is what we always use.”

Avoid switching frameworks mid-build. Re-platforming after development has started is one of the most expensive mistakes founders make; it’s cheaper to spend an extra week evaluating up front.

Explore more: More app development guides.

Cross-platform vs native app development FAQs

Is cross-platform app development good enough for a real business, or just for MVPs?

Cross-platform frameworks like Flutter and React Native are used in production by many established, high-traffic apps, not just prototypes. They’re a legitimate long-term choice for most business apps, not only a way to test an idea cheaply.

Which is cheaper: cross-platform or native app development?

Cross-platform is generally cheaper to build and maintain because one team and one codebase cover both iOS and Android. Native development usually costs more since it requires separate specialists and separate codebases for each platform.

Can I start cross-platform and switch to native later?

Yes, some companies do this once they hit a specific, provable performance or feature limitation. It’s a real rewrite, though, so it’s worth confirming the limitation is actually caused by the framework — and not by app design or team execution — before committing to the switch.

Build It With GTStudios

Need help with your website, app, or small-business tech? GTStudios builds web, apps, and software for small businesses. See how GTStudios can help.

Photo: Pooja dhamo / CC BY 4.0, via Wikimedia Commons.

The post Cross-Platform vs Native App Development: A Founder’s Guide appeared first on GTStudios.

This guide covers every practical layer of a production-ready offline-first Flutter app: picking the right local database, designing a sync-ready schema (including the primary-key decision most tutorials skip), safe CRUD patterns, a pending-ops sync queue, background sync when the app is closed, conflict resolution, and schema migrations — with package versions and platform behavior verified against current documentation, not guesswork.

Quick Answer

Use sqflite (v2.4.3, a Flutter Favorite from Tekartik) or Drift (v2.34.x) with connectivity_plus to build an offline-first Flutter app. Write every change to SQLite first with a synced = 0 flag and a UUID primary key, queue the change in a pending_ops table, then flush that queue to your API whenever connectivity_plus reports an active interface — always confirming real internet access with a lightweight HEAD request first, since a Wi-Fi connection with no upstream route (a hotel captive portal, for example) still reports ‘connected.’

Why Offline-First Changes Your Architecture

In an online-first app the network comes first: the UI blocks on a fetch, caches the result, and shows a cached fallback on failure. In an offline-first app the local database comes first — every read and write hits SQLite immediately, and the network becomes a background concern. Users get instant responses regardless of signal strength.

The practical implication is that every table needing remote persistence must carry sync metadata: a synced flag, an updated_at timestamp stored in UTC milliseconds, and ideally a version counter. Deletes should be soft (is_deleted = 1) rather than hard, so the sync engine can propagate the removal to the server before the row disappears locally. These design decisions — sync flags, soft deletes, and sync-safe primary keys — are what separate a real offline-first app from one that just caches API responses.

Choosing Your Local Database: sqflite vs. Drift vs. Hive/Isar

Flutter does not use expo-sqlite — that package belongs to the React Native/Expo ecosystem and doesn’t exist on pub.dev. For raw SQL control, sqflite (Tekartik, v2.4.3) is the standard choice: it runs natively on Android, iOS, and macOS and moves database I/O to a background thread automatically. For Linux or Windows, add sqflite_common_ffi and call sqfliteFfiInit() before opening any database; experimental web support comes via sqflite_common_ffi_web, which stores data in browser IndexedDB.

Drift (v2.34.x) sits on top of sqlite3 and is now the more common default for new projects: it generates type-safe Dart from your schema, exposes reactive Streams so your UI updates automatically when rows change, handles isolate threading for you, and runs on every platform Flutter targets, web included. If you want compile-time-checked queries and reactive rebuilds without hand-rolling them, start with Drift; if you want direct SQL and the smallest possible dependency footprint, sqflite is still solid.

Avoid Hive and Isar for new offline-first projects in 2026. Hive’s development has stalled, and Isar’s original repository is unmaintained by its author — a community fork (isar_community on pub.dev) keeps it alive, but adopting it means taking on a smaller, less certain maintenance guarantee than SQL-backed options. sqflite and Drift are both actively maintained and are the safer long-term bet.

Design a Sync-Ready Data Model

Bake sync metadata into every table from the start: CREATE TABLE tasks(id TEXT PRIMARY KEY, title TEXT NOT NULL, updated_at INTEGER NOT NULL, synced INTEGER NOT NULL DEFAULT 0, is_deleted INTEGER NOT NULL DEFAULT 0). Store updated_at in UTC milliseconds — never local device time — so timestamps from devices in different time zones compare correctly.

Mirror the schema in a Dart model with toMap() and fromMap() helpers that feed directly into db.insert(), db.update(), and query results. Keep the model thin — field mapping only, no business logic. Add an index on synced so your sync query (WHERE synced = 0) scans only unsynced rows: CREATE INDEX idx_tasks_synced ON tasks(synced). On tables with thousands of rows this index is the difference between a sub-millisecond lookup and a full-table scan on every sync cycle.

UUID or Auto-Increment: Choosing a Primary Key for Sync

This is the decision most offline-first tutorials skip, and it causes real bugs later. INTEGER PRIMARY KEY AUTOINCREMENT is fine for a single-device, single-source app, but it breaks the moment two offline devices each create a row — both assign id = 1, and your server has no way to tell them apart when both sync up.

Generate a UUID on the client at creation time and use it as the primary key, both locally and on the server. The current uuid package on pub.dev supports v4 (fully random) and v7 (time-ordered) generation. Use v4 for a simple random identifier; use v7 when you also want IDs that sort roughly by creation time, which helps with pagination and index locality on the server. Either variant makes every insert globally unique with zero coordination, so sync becomes a pure upsert — the server never needs to remap a client-generated ID to a server-generated one. The tradeoff is a slightly larger primary key (16 bytes vs. 4-8) and non-sequential storage, which is a fair price for eliminating an entire class of sync bugs.

Build the Database Helper and CRUD Layer

Open the database once and reuse that single instance across the app — never open a fresh connection per operation, since sqflite serializes writes and repeated open/close calls add latency for no benefit. A typical helper wraps openDatabase() in a singleton, defines onCreate for the initial schema, and defines onUpgrade for migrations (covered below).

Every CRUD call should touch two things at once: the actual row, and its sync metadata. On insert, set synced = 0 and updated_at = DateTime.now().toUtc().millisecondsSinceEpoch. On update, bump updated_at again and reset synced to 0 so the row is picked up on the next sync pass. On delete, don’t call db.delete() directly — set is_deleted = 1 and synced = 0 instead, so the row’s removal can still be pushed to the server before it’s purged locally. Wrap multi-row writes in db.transaction() so a partial failure can’t leave the local database in a half-synced state.

Syncing to Your Backend With a Pending-Ops Queue

A synced column alone only tells you a row is dirty — it doesn’t tell you what happened to it. A dedicated pending_ops table (id, entity_table, entity_id, op_type, payload, created_at) records every insert, update, and delete as a discrete, ordered operation. That matters because a row can be created and then deleted while still offline; a single synced flag can’t represent that sequence, but two rows in pending_ops can.

Flush the queue in created_at order: send each operation, mark it complete (or delete it) only after the server confirms, and leave it in place on failure so the next sync attempt retries it. This also gives you a natural place to add exponential backoff and per-operation retry counts without touching your core tables.

Detect Real Connectivity, Not Just a Wi-Fi Icon

connectivity_plus reports which network interface is active — Wi-Fi, mobile, ethernet, or none — but it does not confirm that interface can actually reach the internet. A device on hotel or airport Wi-Fi behind a captive portal, or on a Wi-Fi network with a dead upstream link, will still report a connected interface with zero real connectivity.

Treat connectivity_plus as a trigger to attempt sync, not proof that sync will succeed. Before flushing the pending_ops queue, send a lightweight HEAD request to your own API’s health endpoint (or use a package like internet_connection_checker_plus, which layers real reachability checks on top of connectivity_plus). If that check fails, hold the queue and retry on the next connectivity change event instead of burning a failed sync attempt.

Running Sync in the Background When the App Is Closed

For sync to run when the app isn’t in the foreground, use the workmanager package, which wraps Android’s WorkManager and iOS’s BGTaskScheduler behind one Dart API. The two platforms behave very differently, and treating them the same is a common source of ‘background sync doesn’t work’ bugs.

On Android, WorkManager enforces a 15-minute minimum interval for periodic work, and the system generally honors it closely on stock Android. On iOS, BGTaskScheduler is best-effort only: you register a preferred interval, but iOS decides the actual run time based on battery level, network conditions, and the user’s usage patterns, and it can delay or skip a run entirely. iOS also distinguishes BGAppRefreshTask (short work, roughly 30 seconds) from BGProcessingTask (longer jobs the OS runs when the device is idle and charging). Design your sync logic to be idempotent and safe to run late — never assume a background sync fires on a predictable schedule on iOS, and always let a foreground app-resume trigger an immediate sync as a fallback.

Conflict Resolution: Choosing a Strategy

The simplest strategy is last-write-wins: compare the updated_at timestamp on the client’s pending change against the server’s stored value, and keep whichever is newer. This works well for single-owner data like personal notes or settings, where the odds of a true concurrent edit are low and the stakes of losing a stale write are minor.

For records that multiple users or devices genuinely edit concurrently, last-write-wins can silently discard real work. A version counter (bump it on every write, reject a push whose base version doesn’t match the server’s current version) turns a silent overwrite into a detectable conflict you can surface to the user or merge field-by-field. For structured records, field-level merging — comparing each column’s updated_at independently rather than the whole row — preserves more of both edits and is worth the extra complexity for high-collaboration entities like shared task lists or shared documents.

Schema Migrations Without Losing Local Data

openDatabase() takes a version number and an onUpgrade(db, oldVersion, newVersion) callback that sqflite calls automatically when it detects the on-disk schema version is behind the version your code declares. Inside onUpgrade, run the specific ALTER TABLE statements needed to move from each old version to the next — modern SQLite supports ALTER TABLE … ADD COLUMN directly, plus RENAME COLUMN (added in SQLite 3.25.0) and DROP COLUMN (added in SQLite 3.35.0), which are both well within the SQLite versions bundled with current sqflite and Drift releases. DROP COLUMN has limits, though: it only works on a column that isn’t part of a primary key, a UNIQUE constraint, an index, or referenced by a trigger, view, CHECK constraint, or foreign key. For those cases, or for anything ALTER TABLE can’t express (like changing a column’s type), you still need to create a new table, copy the data across, and drop the old one.

Write migrations as a sequence of if (oldVersion < N) blocks rather than one big conditional, so a device that's several versions behind runs every intermediate migration in order. Always test the upgrade path from your oldest still-supported schema version, not just from the previous release — a user who hasn't opened the app in eight months will jump several versions at once.

Tips and Common Mistakes

Don’t call setState or rebuild the whole list on every sync tick — query only the rows that changed, or use Drift’s reactive Streams so the UI updates itself. Don’t skip the synced index; on a table with more than a few hundred rows, an unindexed WHERE synced = 0 scan on every sync cycle is a measurable performance hit. Don’t trust connectivity_plus alone to gate a sync attempt — pair it with a real reachability check. And don’t hard-delete rows the moment a user deletes them locally; a soft delete that’s purged only after server confirmation is what makes deletes actually sync instead of silently disappearing from one device and reappearing after the next pull.

offline-first flutter app with sqlite FAQs

Is expo_sqlite available for Flutter?

No. expo-sqlite is a React Native/Expo-only package and isn’t published for Flutter. The Flutter equivalent is sqflite (or Drift if you want a type-safe query layer on top of SQLite).

Which platforms does sqflite support?

sqflite supports Android, iOS, and macOS natively. Linux, Windows, and the Dart VM are supported via the companion sqflite_common_ffi package, and web support is available experimentally through sqflite_common_ffi_web, which persists data to browser IndexedDB.

How do I handle conflicts when two devices edit the same record offline?

For low-collision data, compare updated_at timestamps and keep the newer write (last-write-wins). For records multiple users actively co-edit, use a version counter to detect conflicting writes, or merge field-by-field using each column’s own updated_at rather than resolving at the whole-row level.

How do I migrate a sqflite database schema when I add a new column?

Bump the version number passed to openDatabase() and add a check inside onUpgrade — if (oldVersion < newVersion) db.execute('ALTER TABLE tasks ADD COLUMN priority INTEGER DEFAULT 0'). Modern SQLite also supports ALTER TABLE ... RENAME COLUMN (since 3.25.0) and DROP COLUMN (since 3.35.0) directly. DROP COLUMN can't be used on a column that's part of a primary key, a UNIQUE constraint, an index, or referenced by a trigger, view, or CHECK/foreign-key constraint — those cases still require creating a new table and copying the data over.

Does connectivity_plus guarantee that the internet is reachable?

No. It only reports which network interface is active (Wi-Fi, mobile data, none), not whether that interface has real upstream internet access — a captive portal or dead Wi-Fi link still reads as ‘connected.’ Confirm reachability separately with a lightweight HEAD request or a package like internet_connection_checker_plus before syncing.

Should I use sqflite or Drift for a new Flutter project?

Drift (currently v2.34.x) is the more common default in 2026 because it adds type-safe generated queries, reactive Streams, automatic isolate threading, and full web support on top of SQLite. Choose sqflite instead if you want to write raw SQL directly with the smallest possible dependency surface.

How do I safely delete records in an offline-first app?

Use a soft delete: set is_deleted = 1 and synced = 0 instead of calling db.delete(). Your sync engine pushes the deletion to the server, and only after that push is confirmed should the row be purged from the local database and, if applicable, from the server.

Why should I use a pending_ops table instead of just a synced column?

A synced flag tells you a row is dirty, but not what happened to it. A pending_ops table records each insert, update, and delete as its own ordered operation, which correctly captures sequences like ‘created then deleted while offline’ that a single synced flag on the row can’t represent.

Should I use UUIDs or auto-increment IDs for offline-first primary keys?

Use UUIDs. Auto-increment IDs collide the moment two offline devices each create a row starting from id = 1. A client-generated UUID (v4 for random, v7 if you also want rough time-ordering) makes every row globally unique with no server coordination, turning sync into a simple upsert.

How do I sync data in the background when the app is closed?

Use the workmanager package, which wraps Android’s WorkManager (minimum 15-minute interval, generally honored) and iOS’s BGTaskScheduler (best-effort only, with no guaranteed run time). Write sync logic that’s idempotent and safe to run late, and also trigger a sync on app resume as a fallback, since iOS background runs can be delayed or skipped entirely.

Build It With GTStudios

Need help with your website, app, or small-business tech? GTStudios builds web, apps, and software for small businesses. See how GTStudios can help.

The post Offline-First Flutter App With SQLite: Complete 2026 Guide appeared first on GTStudios.

This is a complete reference for subosito/flutter-action@v2 — every input and output, the channel vs. flutter-version distinction explained clearly, the errors people hit most (including ones the original docs barely cover, like ARM64 runners and self-hosted git ownership failures), and a full working CI/CD pipeline built around it.

Quick Answer

subosito/flutter-action@v2 is the standard GitHub Action for installing the Flutter SDK on a runner (Linux, Windows, and macOS). Add it to a job step with `channel: stable` and `cache: true`, then run `flutter pub get`, `flutter analyze`, `flutter test`, and `flutter build apk` as sequential steps. Set `flutter-version` only to pin an exact SDK build (e.g. `3.44.0`) — never set it to the word “stable,” since that’s a channel name, not a version, and the action will fail to resolve it.

What Is subosito/flutter-action@v2?

subosito/flutter-action is a community-maintained GitHub Action, and `@v2` is its current major version tag — the one referenced in essentially every Flutter CI/CD tutorial, template repo, and Stack Overflow answer you’ll find. Pinning `@v2` (rather than a full tag like `@v2.21.0`) means your workflow automatically picks up bug fixes and new Flutter releases without you editing YAML every time.

Under the hood it downloads a Flutter SDK archive that matches your requested channel/version/architecture, extracts it to the runner’s tool cache, adds it to `PATH`, and (optionally) restores a cached copy on the next run so you’re not re-downloading a multi-hundred-megabyte SDK on every push. It doesn’t run your tests or builds for you — that’s still `flutter test` and `flutter build` steps you write yourself — it just makes sure the right Flutter toolchain exists on the runner before those steps execute.

Every Input and Output, Explained

Inputs: `channel` (release track — stable, beta, dev, or master/main), `flutter-version` (an exact SDK version, a partial match like `3.x`, or on the master channel a git ref), `flutter-version-file` (reads the version from `pubspec.yaml`, `.fvmrc`, or `.fvm/fvm_config.json` instead of hardcoding it), `cache` (caches the Flutter SDK itself between runs — off by default), `pub-cache` (caches your pub dependencies separately, inheriting `cache`’s value if unset), `cache-key`/`cache-path`/`pub-cache-key`/`pub-cache-path` (customize where and how caches are stored, with dynamic tokens like `:os:`, `:channel:`, `:version:`, `:arch:`, and `:hash:`), `architecture` (target CPU architecture), `git-source` (point at a Flutter fork, such as the community Flock mirror, instead of the official repo), and `dry-run` (resolve version info without installing the SDK — useful for debugging cache keys).

Outputs, referenced in later steps as `steps..outputs.`: `CACHE-PATH`, `CACHE-KEY`, `CHANNEL`, `VERSION`, `ARCHITECTURE`, `PUB-CACHE-PATH`, `PUB-CACHE-KEY`, `CACHE-HIT`, and `PUB-CACHE-HIT`. These are useful for logging exactly which Flutter build ran a given job, or for gating a downstream step on whether the SDK cache actually hit — for example, skipping a slow `flutter precache` call when `CACHE-HIT` is `true`.

channel vs. flutter-version: Which Values Are Valid?

`channel` selects a release track and accepts exactly four values: `stable`, `beta`, `dev`, and `master` (`main` also works as an alias). `flutter-version` expects an actual version number — a full version like `3.44.0`, a partial match like `3.x`, or, only on the master channel, a git tag, commit hash, or branch name. Setting `flutter-version: stable` fails because the action tries to resolve “stable” as a version string and can’t find a matching release — you’ll see it error out before the SDK ever installs.

The fix: either set `channel: stable` and leave `flutter-version` empty to always get the latest stable build, or set both `channel: stable` and `flutter-version: 3.44.0` together to pin an exact release while still validating it against the stable track. If you’d rather not hardcode a version at all, use `flutter-version-file: pubspec.yaml` so the action reads the exact SDK version from your pubspec’s `environment` field — that field must specify an exact version (`flutter: 3.44.0`), since version ranges aren’t resolvable by the action.

Fixing “Unable to Determine Flutter Version” and Other Common Errors

“Unable to determine Flutter version for channel: X version: Y architecture: Z” almost always traces back to one of three causes: an invalid `flutter-version` value (see above), a requested version/architecture combination that Google hasn’t published a build for (this happens with brand-new hotfix releases on ARM64 before the corresponding artifact ships), or a stale `dry-run` cache masking a typo in your inputs. Start by removing `flutter-version` entirely and letting `channel` alone resolve the latest build — if that works, the problem is in how you specified the version.

On self-hosted runners you may also hit `fatal: detected dubious ownership in repository`, a Git security check that trips when the runner user doesn’t own the checked-out or cached SDK directory. Add a step before flutter-action that runs `git config –global –add safe.directory ` (matching your workspace or SDK cache path) to resolve it. And if you’re specifically targeting `ubuntu-24.04-arm` or another ARM64-hosted runner, know that ARM64 support has historically lagged behind x64/macOS in this action — check the project’s open issues for your exact Flutter version before assuming the action itself is broken.

subosito/flutter-action vs. Alternatives

subosito/flutter-action remains the default choice and what most existing templates use, but if you hit a wall the action hasn’t fixed yet, `flutter-actions/setup-flutter` is a newer, actively maintained alternative worth knowing about. Migration isn’t a straight copy-paste of input names: subosito/flutter-action’s `flutter-version` input becomes `version` in setup-flutter, while `channel` carries over directly. Cache behavior is comparable rather than different — setup-flutter exposes separate `cache` (pub) and `cache-sdk` (SDK) booleans that both default to `false`, the same off-by-default posture as subosito/flutter-action’s single `cache` input; you have to explicitly opt in to caching in either action. For most projects, stick with subosito/flutter-action@v2 unless you’re specifically blocked on a maintenance-related bug.

Step-by-Step: Building the Workflow File

Create `.github/workflows/flutter-ci.yml` in your repo. Trigger it with `on: push` and `on: pull_request` targeting your default branch, choose `runs-on: ubuntu-latest` for Android/web builds (use `macos-latest` for iOS or macOS-desktop), then add the action: `uses: subosito/flutter-action@v2` with `with: channel: stable` and `cache: true`. Follow it with `flutter pub get`, `flutter analyze`, `flutter test`, and `flutter build apk –release` (or `flutter build ios –release –no-codesign` for an unsigned iOS build) as separate `run:` steps so failures are attributed to the right stage in the Actions log.

For matrix builds across Android and iOS in one workflow, define a `strategy.matrix` with `os: [ubuntu-latest, macos-latest]` and reference `${{ matrix.os }}` in `runs-on` — each OS gets its own job with the flutter-action step re-run per runner, since the SDK cache doesn’t share across operating systems.

Adding Deployment and Secrets

Store your Android keystore (base64-encoded) and Apple certificates/provisioning profiles as GitHub Encrypted Secrets — never commit them. Decode the keystore in a step before `flutter build appbundle`, reference the secrets via `${{ secrets.YOUR_SECRET_NAME }}`, and hand the signed artifact to a deployment action like `wzieba/Firebase-Distribution-Github-Action` for Firebase App Distribution, or a fastlane lane for TestFlight/Play Store uploads. Gate deployment steps with `if: github.ref == ‘refs/heads/main’` so only merges to your release branch actually ship a build.

subosito/flutter-action@v2 FAQs

What is subosito/flutter-action@v2?

It’s a GitHub Action that installs the Flutter SDK on a runner (Linux, Windows, or macOS) so subsequent workflow steps can run flutter commands. @v2 is its current major version tag, and it’s the de facto standard used across nearly all Flutter CI/CD workflows on GitHub.

Is flutter-version: stable a valid value?

No. “stable” is a channel name, not a version number. Use channel: stable instead, and leave flutter-version empty (for the latest build) or set it to an exact version like 3.44.0 (to pin a release on that channel).

Which Flutter GitHub Action should I use?

subosito/flutter-action@v2 is the safe default — it’s what most templates and tutorials use. Consider flutter-actions/setup-flutter only if you need more granular cache control or hit a subosito/flutter-action bug that hasn’t been patched yet; migrating between the two means renaming flutter-version to version, since input names aren’t identical.

How do I pin an exact Flutter version instead of always using the latest stable?

Set both channel: stable and flutter-version: 3.44.0 (or whatever exact version you need) in the action’s with: block. Setting flutter-version alone without a channel also works but is less explicit.

Can I build for both Android and iOS in the same workflow file?

Yes, using a build matrix with os: [ubuntu-latest, macos-latest] under strategy.matrix, referencing ${{ matrix.os }} in runs-on. Each OS runs the flutter-action step and build commands independently since caches don’t share across operating systems.

How do I make the pipeline run only on pull requests and not on every push?

Remove the push trigger and keep only on: pull_request in your workflow’s on: block, optionally scoped to specific branches with pull_request: branches: [main].

Why is my flutter test step failing in CI but passing locally?

Usually a Flutter/Dart version mismatch — pin flutter-version or flutter-version-file to match your local SDK exactly. Other common causes are missing generated files (run build_runner in CI too) or platform-specific test dependencies not installed on the runner.

How do I fix “Unable to determine Flutter version for channel: stable”?

Remove flutter-version and rely on channel alone first to confirm the action itself works. If the error is specific to a version/architecture combo, that build may not exist yet for your target architecture (common with brand-new releases on ARM64) — try a slightly older pinned version.

How do I fix “detected dubious ownership in repository” on a self-hosted runner?

Add a step before flutter-action that runs git config –global –add safe.directory , pointing at your workspace or SDK cache directory. This is a Git security check unrelated to Flutter itself.

Get More from subosito/flutter-action@v2

Log the coasters, stadiums, and venues you’ve experienced, rate subosito/flutter-action@v2, and see what your friends thought. Get the ThrillZing app.

The post subosito/flutter-action@v2: Complete Reference & Setup Guide appeared first on GTStudios.

This checklist covers the eight things most likely to trip you up before you hit submit, for both the iOS App Store and Google Play. Work through each item once and you’ll avoid the days of back-and-forth that first-time submitters often run into.

Quick Answer

Before submitting a Flutter app, verify your pubspec.yaml version numbers, code signing setup, build format (AAB for Android, IPA for iOS), target SDK levels, permissions, privacy policy URL, store assets, and that you’ve tested a release build on a real device — not just in debug mode.

The 8-Item Flutter Submission Checklist

1. Version numbers in pubspec.yaml. Your version follows the format version: 1.0.0+1, where the number before the plus sign is the user-visible version name and the integer after it is the build number. Both stores require the build number to increment with every upload — submitting the same build number twice will cause an immediate rejection. Start new projects at 1.0.0+1 and never reuse a build number.

2. Code signing is configured correctly. On iOS, you need a valid Distribution Certificate and an App Store Provisioning Profile generated in Apple’s Certificates, Identifiers & Profiles portal. After April 28, 2026, Apple requires all submissions to be built with Xcode 26 or later. Open ios/Runner.xcworkspace, set the build target to Any iOS Device (not a simulator), and confirm signing under Product > Archive before running flutter build ipa –release. On Android, generate your upload keystore with keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload, reference it in key.properties, and keep both files out of version control. Because new apps must enroll in Play App Signing, Google holds the actual app signing key — if you ever lose your upload keystore, you can request an upload key reset through the Play Console (Setup > App integrity) and continue publishing without losing your app listing.

3. You’re building in the right format. Android requires an Android App Bundle (.aab), not a fat APK. Run flutter build appbundle –release to produce the correct artifact. Adding –obfuscate –split-debug-info=build/app/outputs/symbols obfuscates your Dart code and keeps debug symbols out of the bundle. For iOS, flutter build ipa –release produces the signed archive ready for upload via Xcode Organizer or the Transporter app.

4. SDK targets meet store requirements. For Android, your build.gradle must set both compileSdk = 35 and targetSdk = 35 — Google Play requires apps to target Android 15 (API level 35) for new submissions and updates. Setting minSdk = 24 covers the large majority of active Android devices. For iOS, your project must be built with Xcode 26 or later for submissions after April 28, 2026. Run flutter doctor -v to confirm your toolchain versions before building.

5. Permissions are trimmed and described. Open AndroidManifest.xml and audit every tag — remove anything your app doesn’t actively use, since reviewers flag unused permissions and some third-party plugins inject permissions you may not notice. On iOS, every protected API your app accesses needs a corresponding purpose string in Info.plist. Keys like NSCameraUsageDescription must have a specific, user-facing explanation (for example, ‘Used to scan QR codes for login’). Generic descriptions like ‘Needed for app functionality’ are a common rejection trigger.

6. A hosted privacy policy is in place. Both stores require a privacy policy URL that resolves to a live page — not a PDF, not a Google Docs link, not a staging URL. The policy must describe what data you collect and how it’s used. On iOS, you enter this URL in App Store Connect under App Information and must also complete the App Privacy labels (the ‘nutrition label’ for data collection). On Android, fill out the Data Safety section in Play Console accurately — mismatches between what you declare and what your app actually does can trigger removal after launch.

7. Store assets meet spec. On iOS, your app icon must be 1024×1024px with no transparency, and screenshots for the iPhone 6.9-inch display (1320 × 2868px) are mandatory as of 2026 — missing this size blocks submission. On Android, your store icon must be 512×512px PNG with alpha, and a 1024×500px feature graphic is required. Use flutter_launcher_icons to auto-generate the full set of mipmap directories from a single source image, and generate adaptive icons (transparent foreground layer, solid background) to avoid a plain-square fallback on Android 8+. Remove any debug overlays from screenshots — they cause rejection.

8. You’ve tested a release build on a real device. Running flutter run –release on a physical phone is not optional. Release builds disable debug tooling and apply ProGuard/R8 obfuscation, which can surface crashes and broken deep links that were invisible during development. On iOS, distribute to at least a few testers through TestFlight before submitting — Apple recommends validating on TestFlight as a final gate. On Android, use the Internal Testing track in Play Console (typically approved within 30 minutes) to catch any install or launch issues before pushing to production.

Platform-Specific Gotchas Worth Knowing

On iOS, bundle ID consistency is a frequent pain point. The bundle ID must match exactly across your Apple Developer account, App Store Connect record, Xcode’s Runner target, and any third-party services like Firebase. A single mismatch causes signing failures that are time-consuming to untangle. Also confirm that CocoaPods or Swift Package Manager resolves cleanly on your build machine by running pod install from the ios/ directory before archiving.

On Android, bundle size can quietly creep past store limits if you’re not compressing assets. Convert images to WebP format, enable shrinkResources = true and minifyEnabled = true in your release build type, and verify the final AAB size in Play Console’s artifact explorer after upload. Also note that Play App Signing is now required for all new apps — Google securely holds the app signing key and you submit with a separate upload key, which means you can recover from a lost upload keystore by requesting a key reset through the Play Console without losing your app listing.

For apps with user accounts on either platform, both Apple and Google require you to provide a way for users to delete their account from within the app — not just a mailto link. If your app doesn’t have this and you request account-creation, expect rejection.

Common Mistakes That Cause Delays

Submitting without test credentials. If your app requires login and reviewers can’t access it, Apple will reject immediately. Provide demo credentials in the Notes field of App Store Connect’s App Review Information section. Google Play has the same requirement under the App Content section. Use a dedicated reviewer account so you’re not exposing real user data.

Skipping TestFlight or Internal Testing. Uploading straight to production review with an untested build risks catching a crash after the clock starts on review. Both platforms allow pre-release testing tracks that give you a chance to catch launch bugs. The time invested is almost always less than the time lost to a rejection and resubmission cycle.

Forgetting to increment the build number between submissions. If a build is rejected and you fix the issue, you must bump the build number — even if the version name stays the same — before re-uploading. Submitting the same build number after changes is a common source of ‘build already exists’ errors.

Leaving debug flags in. Double-check that dart:developer, debugPrint, and any logging packages are not writing sensitive data in release mode. Flutter automatically strips most debug assertions, but third-party logging libraries may need explicit configuration to stay quiet in production.

Explore more: App Development guides and tutorials.

Flutter App Store Submission FAQs

What’s the difference between flutter build appbundle and flutter build apk?

flutter build appbundle produces an Android App Bundle (.aab), which is required for Google Play submissions. The Play Store uses the AAB to generate optimized APKs for each device configuration, reducing download size. flutter build apk produces a single APK file, which works for direct distribution and testing but cannot be submitted to the Play Store for new apps or updates.

What happens if I lose my Android upload keystore?

If your app is enrolled in Google Play App Signing (required for all new apps), losing your upload keystore is not fatal. Google holds the actual app signing key, so you can request an upload key reset through the Play Console under Setup > App integrity. After submitting the request with a new certificate, Google typically processes it within a few business days and you can resume publishing updates without losing your app listing.

Do I need a separate Apple Developer account for each Flutter app I publish?

No. One Apple Developer Program membership ($99/year for individuals) lets you publish as many apps as you want under your account. You manage each app as a separate record in App Store Connect. The same applies to Google Play — the $25 one-time registration fee covers unlimited app publications under that developer account.

Build It With GTStudios

Need help shipping your app, game, or small-business tech? GTStudios builds web, apps, and games. See how GTStudios can help.

Photo by Fahim Muntashir on Unsplash.

The post Flutter App Store Checklist: 8 Things to Verify Before You Submit appeared first on GTStudios.