👁 Image
GiantCroissant.Lunar.Build.Mobile 0.1.1-ci.113

RFC030: Mobile Component with Integrated Fastlane

👁 NUKE
👁 Fastlane
👁 RFC030

This package implements RFC030, providing NUKE-native mobile build interfaces that integrate seamlessly with Fastlane automation for iOS and Android deployment. It replaces the deprecated RFC018 complex component system with clean, composable NUKE interfaces.

🏗️ Architecture Overview

RFC030 provides a hybrid architecture combining:

• NUKE Orchestration: Build dependencies, parameter management, error handling
• Fastlane Expertise: Mobile platform knowledge, store deployment, certificate management
• Template Distribution: Standardized mobile deployment patterns via NuGet
• Developer Experience: Single command mobile deployment with proper orchestration

📦 Package Contents

Core Interfaces (NUKE-native)

• IMobileBuild: Base mobile interface with common parameters and functionality
• IiOSBuild: iOS-specific build and deployment interface with TestFlight/App Store integration
• IAndroidBuild: Android-specific build and deployment interface with Google Play integration

Services

• IFastlaneExecutionService: NUKE-integrated Fastlane execution bridge
• IFastlaneRunner: Core Fastlane command execution service
• IFastlaneTemplateInstaller: Template installation and management service

Templates (Embedded Resources)

• Fastfile.ios: Comprehensive iOS build automation with TestFlight, Firebase, App Store
• Fastfile.android: Complete Android build automation with Google Play, Firebase
• Gemfile template: Ruby dependency management
• Environment templates: Platform-specific environment variable examples

🚀 Quick Start

1. Add NuGet Package Reference

<PackageReference Include="GiantCroissant.Lunar.Build.Mobile" Version="*" />

2. Implement Mobile Interfaces

using Lunar.Build.Interfaces;
using Microsoft.Extensions.DependencyInjection;

public class Build : NukeBuild, IiOSBuild, IAndroidBuild
{
 // NUKE will automatically provide all mobile parameters via [ParameterPrefix] attributes
 
 public override void ConfigureServices(IServiceCollection services)
 {
 base.ConfigureServices(services);
 
 // Add mobile services with configuration
 services.AddMobileServices(config =>
 {
 config.FastlanePath = "fastlane";
 config.UseBundleExec = true;
 });
 }
}

3. Use Mobile Build Targets

# Build iOS application
nuke BuildiOS --ios-bundle-id com.yourcompany.app --ios-team-id YOUR_TEAM_ID

# Build Android application
nuke BuildAndroid --android-package-name com.yourcompany.app

# Deploy to TestFlight
nuke UploadTestFlight --app-store-api-key-id YOUR_KEY_ID --app-store-api-key-path ./AuthKey.p8

# Deploy to Google Play
nuke UploadGooglePlay --google-play-service-account-path ./service-account.json

# Complete CI/CD pipeline
nuke MobileCIPipeline

🍎 iOS Integration

Available Targets

Key Parameters

[Parameter] string iOSBundleId => "com.giantcroissant.app";
[Parameter] string iOSTeamId => TryGetValue(() => iOSTeamId);
[Parameter] string iOSScheme => "Unity-iPhone";
[Parameter] string iOSExportMethod => "development"; // development, ad-hoc, enterprise, app-store
[Parameter] AbsolutePath iOSProjectPath => RootDirectory / "ios";
[Parameter] string AppStoreApiKeyId => TryGetValue(() => AppStoreApiKeyId);
[Parameter] AbsolutePath AppStoreApiKeyPath => TryGetValue(() => AppStoreApiKeyPath);
[Parameter] string FirebaseAppId => TryGetValue(() => FirebaseAppId);

iOS Fastlane Integration

The iOS interface automatically executes Fastlane lanes:

# Fastfile.ios lanes used by RFC030
lane :build do |options|
 # Comprehensive iOS build with signing, version management, export
end

lane :test do |options|
 # iOS unit and UI testing with simulators
end

lane :upload_testflight do |options|
 # TestFlight upload with App Store Connect API
end

lane :upload_firebase do |options|
 # Firebase App Distribution deployment
end

🤖 Android Integration

Available Targets

Key Parameters

[Parameter] string AndroidPackageName => "com.giantcroissant.app";
[Parameter] string AndroidBuildVariant => "release"; // debug, release
[Parameter] string AndroidBuildType => "apk"; // apk, bundle
[Parameter] AbsolutePath AndroidProjectPath => RootDirectory / "android";
[Parameter] AbsolutePath AndroidKeystorePath => TryGetValue(() => AndroidKeystorePath);
[Parameter] [Secret] string AndroidKeystorePassword => TryGetValue(() => AndroidKeystorePassword);
[Parameter] AbsolutePath GooglePlayServiceAccountPath => TryGetValue(() => GooglePlayServiceAccountPath);
[Parameter] string GooglePlayTrack => "internal"; // internal, alpha, beta, production

Android Fastlane Integration

The Android interface automatically executes Fastlane lanes:

# Fastfile.android lanes used by RFC030
lane :build do |options|
 # Comprehensive Android build with signing, ProGuard, version management
end

lane :unit_test do |options|
 # Android unit testing with JUnit
end

lane :deploy_play_store do |options|
 # Google Play Console deployment with tracks
end

lane :deploy_firebase do |options|
 # Firebase App Distribution deployment
end

⚙️ Service Configuration

Dependency Injection Setup

public override void ConfigureServices(IServiceCollection services)
{
 base.ConfigureServices(services);

 // Basic mobile services
 services.AddMobileServices();

 // Advanced configuration
 services.AddMobileServices(config =>
 {
 config.FastlanePath = "fastlane";
 config.UseBundleExec = true;
 config.GlobalEnvironmentVariables = new Dictionary<string, string>
 {
 ["FASTLANE_SKIP_UPDATE_CHECK"] = "1",
 ["FASTLANE_DISABLE_ANIMATION"] = "1"
 };
 
 // iOS-specific settings
 config.iOS.FastlanePath = "ios/fastlane";
 
 // Android-specific settings 
 config.Android.FastlanePath = "android/fastlane";
 });

 // Platform-specific services
 services.AddiOSServices(ios =>
 {
 ios.FastlanePath = "ios/fastlane";
 });

 services.AddAndroidServices(android =>
 {
 android.FastlanePath = "android/fastlane";
 });
}

Service Usage in Targets

Target CustomMobileTarget => _ => _
 .Executes(async () =>
 {
 // Get mobile services helper
 var mobileServices = ServiceProvider.GetMobileServices();
 
 // Validate environment
 var validation = await mobileServices.ValidateEnvironmentAsync(MobilePlatform.iOS);
 
 // Execute custom lane
 var parameters = new Dictionary<string, string>
 {
 ["custom_param"] = "value"
 };
 
 var result = await mobileServices.ExecuteLaneAsync("ios", "custom_lane", parameters);
 
 if (!result.IsSuccess)
 {
 throw new InvalidOperationException($"Custom lane failed: {result.ErrorMessage}");
 }
 });

📋 Template Management

Automatic Template Installation

Templates are automatically installed when needed, but you can also manage them explicitly:

Target InstallTemplates => _ => _
 .Executes(async () =>
 {
 var mobileServices = ServiceProvider.GetMobileServices();
 
 // Install iOS templates
 var iOSResult = await mobileServices.TemplateInstaller.InstallTemplatesAsync(
 targetDirectory: "ios",
 platform: MobilePlatform.iOS,
 options: new FastlaneTemplateOptions
 {
 InstallGemfile = true,
 InstallEnvironmentTemplate = true,
 OverwriteExisting = false,
 Customizations = new Dictionary<string, string>
 {
 ["app_identifier"] = iOSBundleId,
 ["team_id"] = iOSTeamId ?? ""
 }
 });
 
 // Install Android templates
 var androidResult = await mobileServices.TemplateInstaller.InstallTemplatesAsync(
 targetDirectory: "android",
 platform: MobilePlatform.Android,
 options: new FastlaneTemplateOptions
 {
 InstallGemfile = true,
 InstallEnvironmentTemplate = true,
 Customizations = new Dictionary<string, string>
 {
 ["package_name"] = AndroidPackageName
 }
 });
 });

Template Status Checking

Target CheckTemplateStatus => _ => _
 .Executes(async () =>
 {
 var installer = ServiceProvider.GetRequiredService<IFastlaneTemplateInstaller>();
 
 var status = await installer.CheckTemplateStatusAsync("ios", MobilePlatform.iOS);
 
 Log.Information("Template Status: {Status}", status.IsInstalled ? "Installed" : "Missing");
 Log.Information("Up to Date: {UpToDate}", status.IsUpToDate);
 Log.Information("Message: {Message}", status.Message);
 });

🔧 Advanced Usage

Custom Mobile Orchestration

public class AdvancedMobileBuild : NukeBuild, IiOSBuild, IAndroidBuild
{
 Target BuildAllPlatforms => _ => _
 .Description("Build all mobile platforms with custom logic")
 .DependsOn(ValidateMobileEnvironment)
 .Executes(async () =>
 {
 var platforms = new[] { "iOS", "Android" };
 var tasks = new List<Task<bool>>();
 
 foreach (var platform in platforms)
 {
 tasks.Add(BuildPlatformAsync(platform));
 }
 
 var results = await Task.WhenAll(tasks);
 var successCount = results.Count(r => r);
 
 Log.Information("✅ {SuccessCount}/{TotalCount} platforms built successfully", 
 successCount, platforms.Length);
 
 if (successCount < platforms.Length)
 {
 throw new InvalidOperationException("One or more platform builds failed");
 }
 });

 private async Task<bool> BuildPlatformAsync(string platform)
 {
 try
 {
 var mobileServices = ServiceProvider.GetMobileServices();
 var parameters = CreatePlatformParameters(platform);
 
 var result = await mobileServices.ExecuteLaneAsync(
 platform.ToLowerInvariant(), 
 "build", 
 parameters, 
 FastlaneWorkingDirectory);
 
 return result.IsSuccess;
 }
 catch (Exception ex)
 {
 Log.Error(ex, "❌ {Platform} build failed", platform);
 return false;
 }
 }
}

Environment-Specific Deployment

Target DeployByEnvironment => _ => _
 .Executes(() =>
 {
 var environment = Environment.GetEnvironmentVariable("BUILD_ENVIRONMENT") ?? "development";
 
 Log.Information("🚀 Deploying to {Environment} environment", environment);
 
 var deploymentTargets = environment.ToLowerInvariant() switch
 {
 "production" => new[] { UploadTestFlight, UploadGooglePlay },
 "staging" => new[] { UploadFirebase, UploadFirebaseAndroid },
 "development" => new[] { UploadFirebase, UploadFirebaseAndroid },
 _ => throw new InvalidOperationException($"Unknown environment: {environment}")
 };
 
 foreach (var target in deploymentTargets)
 {
 try
 {
 target.Invoke();
 }
 catch (Exception ex)
 {
 Log.Error(ex, "❌ Deployment target failed: {Target}", target.Name);
 throw;
 }
 }
 });

🔍 Troubleshooting

Common Issues

1. Fastlane Not Found

Error: Fastlane not available or not properly configured

Solution: Install Fastlane using gem or bundle:

gem install fastlane
# or
bundle install

2. Template Installation Failed

Error: Could not find Fastfile template for iOS

Solution: Templates are embedded in the NuGet package. Verify package installation:

dotnet list package | grep Lunar.Build.Mobile

3. iOS Code Signing Issues

Error: Code signing failed

Solutions:

• Verify Team ID: --ios-team-id YOUR_TEAM_ID
• Configure Match: --match-git-url https://github.com/yourcompany/certificates
• Use automatic signing: --automatic-code-signing true

4. Android Signing Issues

Error: Android signing configuration is incomplete

Solutions:

• Provide keystore: --android-keystore-path ./release.keystore
• Set passwords via environment variables:

  export ANDROID_KEYSTORE_PASSWORD=your_password
  export ANDROID_KEY_PASSWORD=your_key_password
  

Debug Mode

Enable verbose logging for troubleshooting:

nuke BuildiOS --verbosity verbose

Or set log level in build:

public override LogLevel LogLevel => LogLevel.Debug;

📚 Documentation Links

• NUKE Build System
• Fastlane Documentation
• iOS Deployment Guide
• Android Publishing Guide

🤝 Contributing

This component follows the NUKE-native interface pattern established in the critical architectural pivot (August 2025). When contributing:

1. Follow NUKE Patterns: Use [ParameterPrefix], TryGetValue(), TryDependsOn<T>()
2. Interface Composition: Clean interface composition for mobile builds
3. Service Integration: Use dependency injection for service management
4. Template Management: Maintain embedded Fastlane templates as resources

📄 License

This component is part of the GiantCroissant Lunar Build System and follows the same licensing terms.

RFC030: Mobile Component with Integrated Fastlane - Bringing NUKE orchestration and Fastlane expertise together for seamless mobile deployment automation.