Flutter Mobile App Template: Engineering a Cross-Platform Delivery Contract

Created: May 20, 2026 Updated: May 20, 2026

The platform engineering problem

Every CI/CD platform accumulates gaps over time. You solve Java, Node, Python, Go, and Rust, and then one day a team shows up with Flutter. Flutter is not a variant of Android or iOS development — it is a build system that sits above two entirely different native toolchains, manages its own dependency graph through pub, drives Gradle and Xcode as implementation details, and places its outputs in paths that neither native pipeline expects. A Gradle wrapper lives under android/, not at the repository root. iOS archives come from flutter build ipa, not from direct xcodebuild invocations. Neither output path matches what existing Android SDK or Xcode blueprint actions assume.

Cloud Ops Works already had mature delivery templates for a dozen application stacks. What it lacked was a Flutter template that answered the real operational questions: which branch model governs environments, how are versions calculated, how do Android and iOS build jobs fit into the same CI matrix, where do signing inputs live, and how does a downstream application repository stay synchronized with platform changes without copying workflow YAML by hand?

The fluttermobile-app-template was designed to answer those questions — in the same terms the rest of the Cloud Ops Works platform already uses. This article reconstructs how it got there: the architecture decisions made up front, the failures that shaped the implementation, and the operational patterns that came out of it. Planning and implementation were driven using OMX (oh-my-codex), a multi-agent AI tooling layer that provided architecture analysis, working memory, and session continuity across the work.

The decision: do not retrofit the wrong template

When extending a delivery platform to a new stack, the fastest first implementation is rarely the correct one. For Flutter, the obvious shortcut was to clone the Android SDK template, add an iOS job, and patch until the sample repository turned green. That path was evaluated and rejected explicitly before a single workflow line was written.

The OMX architecture analysis session documented four implementation options. The first two — inlining Flutter commands directly in workflow files, or creating repo-local composite actions under .github/actions/flutter/ — were fast to implement and wrong for the same reason: they would have embedded reusable platform behavior inside one template, making it unavailable to any other Flutter repository and impossible to fix centrally.

The third option was the right one: build a Flutter-specific action family in the shared cloudopsworks/blueprints repository and wire the template workflows as thin orchestration over those actions. That is exactly how the rest of the platform works. The Java template calls ./bp/ci/java/*, the Node template calls ./bp/ci/node/*. Flutter deserved the same treatment.

The fourth option was the most tempting technically: reuse the existing ci/androidsdk/* and ci/xcode/* blueprint actions with wrapper shims. Symlink the Gradle wrapper to the repository root, pre-install Flutter before the native Xcode action runs, adapt the artifact globs manually. It would have reduced the initial diff size. It was still wrong. The Android SDK build action expected ./gradlew at checkout root; Flutter keeps its wrapper under android/. The Xcode build action expected direct xcodebuild invocations on a native project; Flutter's iOS build needs Flutter dependency setup, CocoaPods management, and flutter build ipa as the actual orchestrator. Wrapping native actions around a Flutter project would have produced a pipeline that appeared to work until it failed in ways that were genuinely hard to diagnose — because every failure would be ambiguous between Flutter, Gradle, Xcode, the template, and the blueprints.

The ownership model that came out of this decision is what gives the template its long-term value:

Reusable Flutter build behavior lives in cloudopsworks/blueprints/ci/flutter/*
Template defaults and orchestration live in fluttermobile-app-template
Sample repositories validate and consume the template
Private downstream applications use the template without becoming the source of platform documentation

That boundary means a platform engineer can fix one blueprint action and improve every derived repository automatically. It also means a mobile engineer does not need to understand the full blueprint system to use the template correctly.

The configuration contract

Once the architecture was settled, the next design problem was configuration. Mobile CI is not a clean Cartesian product. Android and iOS are fundamentally different jobs — different runners, different costs, different signing requirements, different artifact shapes. A matrix that crosses Android SDK versions against Xcode schemes produces invalid combinations. The template needed a configuration model that was explicit about platform selection and could drive a dynamic build matrix without requiring teams to fork workflow files for every combination.

The answer was .cloudopsworks/vars/inputs-global.yaml with a top-level flutter: section. Its shape reflects how mobile builds actually work:

Flutter SDK channel and version control which SDK the pipeline installs
project_path tells build actions where the Flutter root is relative to checkout
platforms — android, ios, or both — drives which build matrix rows are emitted
Quality gates (pub_get, analyze, test) are opt-out, not opt-in
The Android block describes runner, SDK label, artifact types (APK and/or AAB), deployable artifact selection, and split-per-ABI behavior
The iOS block describes macOS runner, Xcode version, scheme, code signing mode, export method, and whether unsigned smoke builds are acceptable

Two decisions in that shape deserve specific attention from an architecture standpoint.

AAB (Android App Bundle) and APK are both valid build outputs but not equivalent for deployment. AABs are for store delivery; device farms expect APKs. The configuration model makes that distinction explicit through deployable_artifact_type, so a deploy job can refuse to forward a AAB-only build to AWS Device Farm without requiring the team to understand the device-farm contract directly.

iOS PR builds are also explicitly opt-in. macOS GitHub Actions minutes cost roughly ten times what Linux minutes cost. The default is Android-on-Linux for pull requests, with iOS enabled per deliberate configuration. That is a cost control that teams should consciously override rather than inherit by accident.

Teams express choices — Android-only PRs, signed IPAs only on release paths, device-farm deploy only when credentials are present — through configuration, not through workflow forks. That distinction keeps the upgrade path clean.

Pipeline architecture: quality, builds, artifacts, deploy, scan

The workflow pipeline follows a shape that an engineer can reason about under pressure. A pipeline that is clever when everything is working is painful when something fails at 2 AM.

The pipeline opens with a preload job that checks out application source, fetches the Cloud Ops Works blueprint bundle from cloudopsworks/blueprints, and runs ci/config to establish environment, version, and build matrix context. Nothing downstream runs until that phase succeeds and its outputs are available.

Quality runs first on Linux, before any platform-specific build job starts. flutter pub get, flutter analyze, flutter test — fast feedback on common failures that do not require macOS minutes. Android and iOS build jobs then run independently from the matrix emitted by the Flutter configuration. Artifacts upload from Flutter's actual output directories. A release-assets collection step downloads build artifacts before the GitHub Release job runs, solving the common problem where a release event fires against artifacts that were never actually fetched.

One pipeline decision deserves explicit attention: the v5.10 blueprint channel reference.

During the debugging phase, template workflows were pinned to individual blueprint patch tags — @v5.10.33, then @v5.10.34 — because active debugging required proving that a specific patch was in effect. That was correct behavior during debugging and wrong as a steady state. A template pinned to a blueprint patch requires a template release every time a blueprint patch ships. The v5.10 channel reference means compatible fixes flow to derived repositories without forcing a template update for every blueprint repair. Teams on v5.10 receive platform improvements automatically within the compatible minor channel. Template releases happen when template behavior actually changes, not when the platform ships a patch.

The operational rule is straightforward: keep orchestration workflow refs on cloudopsworks/blueprints/cd/checkout@v5.10 with blueprint_ref: v5.10. Do not chase patch tags in production repositories.

When the sample failed: seven lessons from CI

A template that has not been validated against a real sample repository is still a hypothesis. The debugging phase started when the first sample runs were pushed — and began failing not in Flutter builds, not in iOS signing, but before either concern had a chance to run.

Identity failure. The shared checkout module reported No module marker file found and attempted a nonsense repository URL. Sample runs 26111084435 and 26111084436 documented this clearly. The template was not being recognized as a Cloud Ops Works repository at all. Without that classification, every downstream workflow decision was working from a bad premise.

This is a category of failure that platform engineers encounter whenever a new template family is added. Each family needs a marker file that tells shared automation what kind of repository it handles. Terraform modules have theirs; Java, Node, and Xcode templates have theirs. Flutter needed its own. The fix landed in blueprints v5.10.33, which taught the checkout module's version-check logic to recognize .cloudopsworks/.fluttermobile and .cloudopsworks/.flutter. More importantly, it confirmed that Flutter needed to be a first-class Cloud Ops Works template with its own repository type — not an Android variant with a different source tree.

Shell compatibility on macOS. After checkout was fixed, failures moved into build behavior. One of the subtler issues was a macOS Bash 3 compatibility problem in the Flutter build action. macOS runners commonly ship with Bash 3 as the default shell, and empty array expansion behaves differently there than in Bash 4 or newer. A composite action that builds a command by optionally appending elements to an array can work cleanly on Linux and fail on macOS depending on how the expansion is written. The iOS lane forced the blueprint actions toward shell behavior that survives the runners real teams actually use, not just the latest Linux default.

Artifact path normalization. The template default sets project_path: ".", which is correct for a Flutter project at the repository root. The artifact action was constructing upload paths by directly joining source_path and project_path, which produced forms like source/./build/.... In shell output that looks harmless. To actions/upload-artifact@v7 the path normalization was enough to cause upload failures. The fix computed a clean project root first: use source_path alone when project_path is ., and append only when it points to an actual subdirectory. This is the kind of bug that only surfaces when someone runs the action against a root-level project, which the sample did.

The iOS fallback chain. Flutter's flutter build ipa is the correct command for signed iOS release artifacts, but real projects do not always match the documentation's happy path. A default Flutter app may have ios/Runner.xcodeproj but not ios/Runner.xcworkspace. Manual provisioning requires metadata decoded from the mobileprovision binary format. Signed fallback flows need explicit archive and export behavior. Each failure mode became a blueprint release:

v5.10.35: signed IPA fallback
v5.10.36: explicit archive/export fallback
v5.10.37: project-only Xcode archive fallback when no workspace file exists
v5.10.38: manual provisioning fallback using decoded mobileprovision metadata

When Android and iOS builds finally turned green — verified in sample run 26119028000 with all jobs succeeding, including Flutter Quality, Android, iOS, both deploy targets, and SAST/SCA scans — the pipeline failed again, this time at deployment. Deploy actions expected APK and IPA artifacts at the artifact root. Flutter artifact downloads preserved nested build subdirectories. Blueprint v5.10.39 added recursive artifact lookup for AWS and GCP mobile deploy actions, and that was the last fix in the series.

Every one of those failures was fixed in the blueprints, not patched into the sample. That discipline is what makes a template durable across derived repositories.

Release line: narrow reasons, clear provenance

The v1.0.x patch series is short enough to read as a debugging trail in version form.

v1.0.0 established the baseline. v1.0.1 through v1.0.3 handled Flutter matrix workflow corrections and removed compatibility aliases that should not have been permanent. v1.0.4 through v1.0.9 are blueprint-fix alignment releases: each one pulled in a specific blueprint patch that resolved a real failure mode. v1.0.10 switched all workflow refs from patch-specific blueprint tags to the v5.10 channel. v1.0.11 added the full template usage runbook. v1.0.12 converted the runbook from YAML to Markdown, added dual GitVersion presets, and cleaned up ignore rules for AI agent working directories.

One frequently confusing behavior: the version file in the repository may read ahead of the latest published tag when a hotfix branch is being prepared. That is not inconsistency — it is normal GitVersion behavior in a GitFlow-driven repository. The branch name, the version file, and the published GitHub Release tag are related but not synchronized at the same moment. Teams new to GitVersion-driven repositories should not treat those three values as interchangeable. They are three different windows into the same release lineage.

Current stable template is v1.0.12, on the v5.10 blueprint channel.

Operational setup and governance

For a DevOps engineer inheriting or extending this template, the starting point is the GitHub template mechanism, which copies the correct repository structure, markers, and workflow baseline in one operation. After cloning, initialize GitFlow with make gitflow/init, switch to the develop branch, then run make code/init to stamp repository metadata. The Tronador toolchain — which provides make, yq, and GitVersion support — is a prerequisite. Setup failures here typically look like template problems but are actually workstation prerequisites.

The immediate configuration work lives in .cloudopsworks/vars/inputs-global.yaml: identity fields, platform selection, quality gate toggles, and signing mode. Make platform selection deliberately. For most teams starting a new application, Android-on-Linux for PR builds and both platforms for main/release builds is the right default. Enable iOS code signing when certificates and provisioning profiles are in place, not before.

The boundary between what application teams own and what the platform owns is explicit and enforced:

Application-owned: README.md, pubspec.yaml, lib/, test/, Android and iOS app identity, icons, signing settings, .cloudopsworks/vars/inputs-global.yaml, environment input files, repository secrets

Platform-owned: root Makefile, .github/ workflow definitions, .cloudopsworks/labeler.yml, .cloudopsworks/Makefile, .cloudopsworks/LICENSE

That boundary is not bureaucratic overhead. It exists because every derived application that manually edits its workflow definitions becomes a repository that cannot safely receive platform improvements. When teams express choices through supported configuration inputs, the platform can ship blueprint fixes to every derived repository without breaking individual decisions. When a team needs behavior that the current configuration model does not support, the right question is whether that behavior belongs in blueprints — not whether to fork the workflow file.

Production validation: what field pressure confirmed

The template's validation did not stop at the sample repository. Private downstream applications using the template faced real delivery pressure — real app names, real signing certificates, real device-farm targets, real release schedules. That pressure validated three patterns the sample repository alone could not exercise.

The configuration separation held under real conditions. Private applications have bundle identifiers, team IDs, API endpoints, and signing assets the template must not know. The division between inputs-global.yaml (platform and build choices), environment input files (deployment-specific overrides), repository secrets (credentials), and application source (business logic) was clean enough that no platform detail leaked into application configuration and no application detail leaked into the platform template.

The upstream-first fix discipline also held. When a private application encountered a deployment failure, the diagnosis pointed to reusable platform behavior — artifact path assumptions, runner compatibility, signing metadata — not to application-specific code. Each fix went into blueprints and became available to every repository on the channel.

Finally, evidence-based debugging held. Failures were diagnosed from workflow run logs and artifact inspection, not from guesswork. When a deploy failed after green builds, the evidence was in the artifact download directory structure, not in vague pipeline failures. Keeping that evidence-first approach prevented patches that would have fixed symptoms without addressing causes.

Troubleshooting reference

Checkout fails before build starts. Look at repository identity first. A Flutter mobile repository needs .cloudopsworks/.fluttermobile. Workflow refs must use cloudopsworks/blueprints/cd/checkout@v5.10 with blueprint_ref: v5.10. Without the marker, checkout cannot classify the repository, and every downstream workflow decision is already working from the wrong starting point.

Android artifacts are missing after a successful build. Flutter APKs land under build/app/outputs/flutter-apk/; AABs land under build/app/outputs/bundle/. These are not the same paths as a native Android template. Verify the configured artifact type matches what the build actually produced before touching workflow files.

iOS builds fail. Separate the failure before choosing the fix. Unsigned smoke build failures and signing failures are different problems with different remedies. Check Xcode version, scheme, whether the project has a workspace file or only a .xcodeproj, code signing mode, certificate availability, export method, and provisioning profile state. The fallback chain added in v5.10.35–v5.10.38 handles most common Flutter iOS configurations — but only if the signing inputs are correct to begin with.

Deployment fails after successful builds. Check the artifact download structure before assuming the build produced wrong output. Mobile deploy jobs use recursive artifact lookup because CI artifact downloads preserve nested build subdirectories. The build contract and the deploy handoff contract are not the same contract.

A downstream application appears to need a workflow change. Stop at the ownership question before editing anything. Is the needed behavior reusable across all Flutter mobile repositories? If yes, it belongs in blueprints. If it is genuinely application-specific, it belongs in vars, secrets, or application source. That question is what keeps one-off pressure from permanently diverging downstream applications from the platform template.

The road ahead

The v1.0.12 template is stable. Two operational gaps remain on the backlog.

The more immediate one is Tronador. The make repos/upgrade command does not yet natively recognize .cloudopsworks/.fluttermobile. The current workaround is to temporarily add a .cloudopsworks/.android compatibility marker, run the upgrade through the Android template detection path with ANDROIDSDK_TEMPLATE=cloudopsworks/fluttermobile-app-template overridden, then remove the marker before committing. It works. It is not clean. Adding native .fluttermobile detection to Tronador's repos/template/init would eliminate the workaround entirely and give Flutter the same upgrade experience as every other template family.

Further out: richer Flutter-specific scan behavior using Dart/mobile-aware Semgrep rules and DependencyTrack SBOM generation from pubspec.lock, more explicit release-asset collection for app store delivery pipelines, and additional mobile deployment providers when the shared blueprints add them.

The real evolution

The fluttermobile-app-template story is what platform engineering looks like when it resists the obvious shortcut.

The shortcut was available the entire time: copy Android YAML, add iOS YAML, patch until something passed. Instead, the work started with a structured architecture review that identified why all three easy paths were wrong, then built the correct structure in the shared blueprints repository before writing any template orchestration. When sample runs failed — and they did, across seven blueprint releases from v5.10.33 through v5.10.39 — each fix landed in the place where every derived repository could benefit, not in the sample just to produce a green run.

For the engineers who will inherit and extend this template: the ownership boundary is not bureaucratic overhead. It is the mechanism that lets the platform improve without breaking downstream applications. The configuration model is not over-engineered — mobile CI genuinely is not a Cartesian matrix, and the shape reflects that. The release history is not noise — each patch points to a failure that was made boring so you do not encounter it in production.

Flutter is now first-class in the Cloud Ops Works delivery platform. The delivery contract — GitFlow, GitVersion, quality gates, artifact management, device-farm deployment, release automation, security scanning — works the same way for a Flutter repository as it does for Java, Node, or any other template family. That consistency is what the template was built to provide.