flutter_tools: Auto-generate ExportOptions.plist for manual iOS code signing #177888

MohammedTarigg · 2025-11-01T20:40:53Z

flutter_tools: Auto-generate ExportOptions.plist for manual iOS code signing

Summary

Enhance flutter build ipa to automatically generate a complete ExportOptions.plist for manual code signing configurations, eliminating the need for users to create and maintain one manually.

Fixes: #177853

Problem

When using manual code signing (CODE_SIGN_STYLE=Manual) with flutter build ipa for Release/Profile builds, the archive succeeds but the export step fails with:

error: exportArchive: "Runner.app" requires a provisioning profile with the Push Notifications and Sign in with Apple features.

Root cause: Flutter generated an incomplete ExportOptions.plist that only included method and uploadBitcode. When using manual signing, xcodebuild -exportArchive requires:

teamID (from project's DEVELOPMENT_TEAM)
signingStyle=manual
provisioningProfiles (mapping bundle ID to provisioning profile UUID)

Without these, Xcode cannot resolve the provisioning profile for export, even if the profile is correctly configured and contains the required entitlements.

Solution

Enhanced _createExportPlist() in BuildIOSArchiveCommand to automatically generate a complete ExportOptions.plist when:

CODE_SIGN_STYLE=Manual is detected for the main app target
Build mode is Release or Profile (production builds only)
A valid provisioning profile can be located and parsed

The generated plist includes:

method (app-store, ad-hoc, enterprise, etc. - respects user's --export-method flag)
teamID (from DEVELOPMENT_TEAM build setting)
signingStyle=manual
provisioningProfiles mapping main app bundle ID to provisioning profile UUID

Fallback behavior:

If profile lookup fails: silently fall back to simple plist (no regression)
For Automatic signing: unchanged behavior
For Debug builds: unchanged behavior (not App Store export)
For multi-target apps (extensions): falls back to simple plist today (see TODO below)

Changes

Core Implementation

Added ProfileData class to encapsulate provisioning profile info (UUID and name)
Refactored profile handling into reusable static methods for testability
Enhanced _createExportPlist() with manual signing detection and profile lookup
Added _findProvisioningProfileUuid() to locate provisioning profiles by specifier
Added _parseProvisioningProfileInfo() to decode provisioning profile data once
Added comprehensive trace logging for debugging

Testing

Created build_ipa_export_plist_test.dart with 7 unit tests covering:
- Manual signing with profile found → enhanced plist generated ✓
- Automatic signing → simple plist (unchanged behavior) ✓
- Debug builds → simple plist (unchanged behavior) ✓
- Different export methods → respected in generated plist ✓
- Profile lookup failures → fallback to simple plist ✓
- Null codeSignStyle → handled gracefully ✓
All existing flutter_tools tests continue to pass

Documentation

Added extensive inline comments explaining:

Enhancement conditions and fallback behavior
Provisioning profile search strategy and error handling
Performance and security considerations
Future enhancements (multi-target support)

Safety & Scope

What This Fixes

✅ Manual signing export failures for apps with Push Notifications / Sign in with Apple
✅ Auto-generates correct plist for any entitlements covered by provisioning profile
✅ Unblocks users from manual --export-options-plist workaround
✅ Improves iOS build UX for enterprise teams doing manual signing

What This Does NOT Change

✅ Automatic signing behavior (unchanged)
✅ Debug builds (unchanged)
✅ CLI interface (no new flags)
✅ Ad-hoc / enterprise distributions (unchanged if not using manual signing)

Known Limitations (Future Enhancements)

Currently only supports single-target apps (main app bundle ID only)
TODO: Multi-target apps with extensions (notification service, widgets, watch, etc.) - each extension target bundle ID may need separate entry in provisioningProfiles dict
TODO: Support for multiple provisioning profiles if app uses multiple signing identities

Pre-merge Checklist

I have signed the CLA
I read the Contributor Guide and Tree Hygiene docs
I linked the issue this fixes (flutter build ipa fails for manual signing unless a custom ExportOptions.plist is provided (Push Notifications / Sign in with Apple entitlements) #177853) and explained the failure scenario
I added documentation and trace logs so developers understand what changed
I added comprehensive unit tests for the new behavior
All existing and new tests pass locally (flutter test packages/flutter_tools)
Code passes linting (dart analyze)

Safety Notes

This code only runs for manual code signing in flutter build ipa for Release/Profile builds
Debug builds and automatic signing behavior are completely unchanged
If no provisioning profile UUID is found, we silently fall back to the old exportOptions.plist logic instead of failing
Added trace-level logging explaining success/fallback scenarios for debugging
No breaking changes - existing workarounds continue to work
Minimal blast radius - only affects manual signing export path

Verification

Users can verify the fix by:

Creating an iOS app with CODE_SIGN_STYLE=Manual, DEVELOPMENT_TEAM set, and Push Notifications entitlements
Running flutter build ipa --release --verbose
Confirming the trace log shows "Generated ExportOptions.plist with teamID, signingStyle=manual, and provisioningProfiles"
Verifying the IPA is successfully created without needing --export-options-plist

Related Issues

Support flutter build ipa with manual signing and provisioning profiles #106612 - Support flutter build ipa with manual signing and provisioning profiles
Flutter build IPA with --export-options-plist not working #113977 - Flutter build IPA with --export-options-plist not working

gemini-code-assist

Code Review

This pull request enhances flutter build ipa to automatically generate a complete ExportOptions.plist for manual code signing configurations. This is a significant improvement for developers using manual signing, especially for apps with entitlements like Push Notifications. The changes include adding logic to detect manual signing, find the correct provisioning profile, and generate an enhanced plist with the necessary signing information. The implementation includes robust fallback mechanisms and extensive logging. New unit tests have been added to cover the new logic, and existing tests are updated. The code is well-documented and follows good practices for testability and maintainability. I have a couple of minor suggestions for improving code style and readability.

packages/flutter_tools/test/commands.shard/hermetic/build_ipa_test.dart

packages/flutter_tools/lib/src/commands/build_ios.dart

…est practices - Simplify FakeXcodeProjectInterpreter.getBuildSettings by defining defaults first, then spreading overrides (eliminates redundant ?? operators) - Replace listSync() with await for (using list()) in _findProvisioningProfileUuid for better asynchronous code style and non-blocking file system operations Addresses code review feedback from PR flutter#177888