GiantCroissant.Lunar.Build.Mobile.iOS 0.1.1-ci.108

Lunar Build Mobile iOS Components

RFC021: iOS Build Integration - Comprehensive iOS build component for the GiantCroissant Lunar Build system.

Overview

This component provides comprehensive iOS build capabilities including:

• Xcode Project Builds: Support for Unity-generated and native Xcode projects
• Code Signing Management: Both automatic and manual code signing workflows
• TestFlight Deployment: Automated upload to TestFlight with App Store Connect API integration
• Firebase App Distribution: Firebase distribution for testing and internal releases
• App Store Submission: Complete App Store submission pipeline
• Environment Validation: macOS, Xcode, and iOS SDK validation

Features

✅ Core iOS Build Capabilities

• Xcode project compilation and archiving
• Unity iOS project support with proven sango-card patterns
• Multiple export methods (development, app-store, enterprise, ad-hoc)
• Build artifact collection and management
• Comprehensive logging and error handling

🔐 Code Signing & Provisioning

• Automatic code signing via Xcode managed provisioning
• Manual code signing with custom provisioning profiles
• Provisioning profile validation and installation
• Certificate management and validation
• Team ID and signing identity configuration

🚀 Deployment & Distribution

• TestFlight Integration:
  • App Store Connect API support
  • Automatic build upload and processing
  • External tester distribution
  • Beta app review information handling
• Firebase App Distribution:
  • Service account authentication
  • Tester email and group management
  • Release notes and versioning
• App Store Submission:
  • Automated submission pipeline
  • Release scheduling and phased rollout
  • Review information management

🧪 Testing & Validation

• iOS Simulator integration for testing
• Unit and UI test execution
• Code coverage collection
• Test result reporting in multiple formats (xcresult, junit)
• Environment and configuration validation

Architecture

Built on RFC018: Build Component Specification patterns:

[BuildComponent("ios")]
public class IosBuildComponent : IBuildComponentV2, IMobileBuildComponent

Service Dependencies

• IFastlaneRunner: Automation pipeline execution
• IProvisioningProfileService: Provisioning profile management
• IXcodeValidationService: Xcode environment validation
• IIosSigningService: Code signing configuration
• ITestFlightService: TestFlight deployment
• IFirebaseDistributionService: Firebase App Distribution

Configuration

iOS Build Context

var iosContext = new IosBuildContext
{
    XcodeProjectPath = "./ios/Unity-iPhone.xcodeproj",
    Scheme = "Unity-iPhone",
    ExportMethod = "development",
    BundleIdentifier = "com.example.app",
    SigningConfig = new IosSigningConfig
    {
        UseAutomaticSigning = true,
        TeamId = "TEAM123456"
    }
};

JSON Configuration

{
  "mobile": {
    "ios": {
      "enabled": true,
      "xcodeProjectPath": "./ios",
      "scheme": "Unity-iPhone",
      "exportOptions": {
        "method": "development",
        "teamID": "YOUR_TEAM_ID",
        "signingStyle": "automatic"
      },
      "deployments": {
        "testflight": {
          "apiKeyId": "XXXXXXXXXX",
          "apiKeyPath": "./fastlane/AuthKey.p8",
          "issuerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        },
        "firebase": {
          "appId": "1:1234567890:ios:abc123def456",
          "serviceAccountKeyFile": "./firebase-service-account.json",
          "testerGroups": ["internal-testers"]
        }
      }
    }
  }
}

Usage Examples

Basic iOS Build

var iosComponent = serviceProvider.GetService<IosBuildComponent>();
var buildContext = new IosBuildContext
{
    XcodeProjectPath = "./ios/Unity-iPhone.xcodeproj",
    Scheme = "Unity-iPhone",
    ExportMethod = "development"
};

var buildSuccess = await iosComponent.BuildAsync(buildContext);

TestFlight Deployment

var deployContext = new IosDeployContext
{
    UploadToTestFlight = true,
    IpaPath = "./build/ios/App.ipa",
    TestFlightConfig = new TestFlightConfig
    {
        ApiKeyId = "XXXXXXXXXX",
        ApiKeyPath = "./fastlane/AuthKey.p8",
        IssuerId = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        DistributeExternal = true,
        Groups = { "Beta Testers" }
    }
};

var deploySuccess = await iosComponent.DeployAsync(deployContext);

Firebase Distribution

var deployContext = new IosDeployContext
{
    UploadToFirebase = true,
    IpaPath = "./build/ios/App.ipa",
    FirebaseConfig = new IosFirebaseDistributionConfig
    {
        AppId = "1:1234567890:ios:abc123def456",
        ServiceAccountKeyFile = "./firebase-service-account.json",
        TesterEmails = { "tester@example.com" },
        TesterGroups = { "internal-team" },
        ReleaseNotes = "Latest iOS build with new features"
    }
};

var deploySuccess = await iosComponent.DeployAsync(deployContext);

Requirements

System Requirements

• macOS: iOS builds require macOS operating system
• Xcode: Latest stable version recommended (15.0+)
• iOS SDK: At least one iOS SDK installed via Xcode
• Fastlane: Ruby gem for automation (gem install fastlane)

Apple Developer Requirements

• Active Apple Developer Program membership
• App Store Connect access for TestFlight/App Store deployment
• Signing certificates and provisioning profiles configured
• App Store Connect API key for automated uploads

Optional Requirements

• Firebase project setup for Firebase App Distribution
• Service account key for Firebase authentication
• Ruby environment for Fastlane (typically included with macOS)

Integration with sango-card Patterns

This implementation leverages proven patterns from the sango-card iOS build system:

• Fastlane Configuration: Based on production-tested Fastfile implementation
• Code Signing Flow: Proven automatic and manual signing workflows
• Version Management: CFBundleVersion and CFBundleShortVersionString handling
• Environment Configuration: Multi-environment support (dev, staging, production)
• Output Management: Structured build artifact organization

Error Handling

Comprehensive error handling with RFC018 BuildComponentException patterns:

try 
{
    var result = await iosComponent.BuildAsync(context);
}
catch (BuildComponentException ex) when (ex.ComponentId == "ios")
{
    // Handle iOS-specific build errors
    _logger.LogError("iOS build failed: {Message}", ex.Message);
}

Testing

Component includes comprehensive test coverage:

• Unit Tests: Component behavior validation
• Integration Tests: Real Xcode project builds
• Mock Services: Testable service implementations
• Validation Tests: Configuration and environment validation

Contributing

This component follows RFC018 Build Component Specification standards:

1. All services implement proper interfaces
2. Comprehensive logging with structured messages
3. Exception handling with BuildComponentException
4. Configuration validation and error reporting
5. Dependency injection patterns throughout

For implementation details, see RFC021: iOS Build Integration.