alphaonedev/ios-deploy

ios-deploy

Purpose

This skill automates iOS app deployment workflows, including archiving apps with Xcode, uploading to TestFlight or App Store Connect, managing certificates and provisioning profiles, and integrating with tools like Fastlane and Xcode Cloud. It streamlines CI/CD for iOS projects.

When to Use

Use this skill when deploying iOS apps to TestFlight for beta testing, submitting to the App Store, or handling signing and provisioning in CI pipelines. Apply it in scenarios involving Fastlane automation, Xcode Cloud builds, or when troubleshooting certificate issues in enterprise environments.

Key Capabilities

• Archive iOS apps using Xcode's command-line tools with specific build configurations.
• Upload builds to TestFlight via App Store Connect API, requiring authentication.
• Manage certificates and provisioning profiles using Fastlane's match or sigh actions.
• Automate workflows with Fastlane lanes for CI, including code signing and beta deployment.
• Integrate with Xcode Cloud for cloud-based builds and automated testing.
• Handle App Store metadata updates via Spaceship API for release notes and screenshots.

Usage Patterns

Always start by ensuring Xcode and Fastlane are installed. For CI integration, wrap commands in scripts that check for environment variables like $FASTLANE_APP_ID. Use in pipelines where builds are triggered on code changes, followed by automated testing and deployment. For local development, run commands interactively to verify outputs before automation. Include error checks in scripts to halt on failures, e.g., verify provisioning profiles exist before archiving.

Common Commands/API

Use Fastlane for most tasks; here's how to execute key operations:

• Archive and build an app: Run xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive -configuration Release. Follow with xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportPath build/export -exportOptionsPlist exportOptions.plist.
• Upload to TestFlight: Use Fastlane: fastlane upload_to_testflight with config in Fastfile: lane :beta do |options| upload_to_testflight(changelog: options[:changelog]) end. Requires $APP_STORE_CONNECT_API_KEY in env vars.
• Manage certificates: Run fastlane match development to create or download profiles; config via Matchfile with type: "development" and git_url: "[email protected]:user/repo.git".
• Xcode Cloud API: Trigger builds via API endpoint: POST to https://api.apple.com/v1/builds with JSON payload { "workflowId": "12345", "sourceBranch": "main" }, authenticated with $XCODE_CLOUD_TOKEN.
• App Store Connect API: Fetch app info with spaceship::Tunes::App.find("com.example.app") in a Ruby script: require 'spaceship'; Spaceship::Tunes.login; app = Spaceship::Tunes::App.find('bundle_id').

Integration Notes

Integrate by adding Fastlane to your project via gem install fastlane, then create a Fastfile in the root directory. For authentication, set env vars like export FASTLANE_SESSION=$APP_STORE_CONNECT_API_KEY for App Store Connect access. Use Xcode Cloud by enabling it in App Store Connect and referencing the workflow ID in scripts. For CI tools like GitHub Actions, include steps like: run: fastlane beta in your YAML file, ensuring dependencies are cached. Handle multiple environments by using Fastlane's lanes, e.g., define a lane for staging with different provisioning profiles.

Error Handling

Common errors include invalid certificates; check with fastlane match nuke development to reset and retry. For upload failures, verify API key with fastlane spaceauth -o and ensure bundle ID matches. If archiving fails due to code signing, run fastcode sign --force and specify the profile in exportOptions.plist: <key>signingStyle</key><string>Manual</string>. Handle network errors in scripts by adding retries, e.g., in bash: for i in {1..3}; do fastlane upload_to_testflight && break || sleep 5; done. Log outputs with fastlane --verbose for debugging.

Concrete Usage Examples

1. Deploy to TestFlight: In a CI script, first build: xcodebuild -scheme MyApp -configuration Release clean build. Then upload: fastlane run upload_to_testflight api_key: $APP_STORE_CONNECT_API_KEY changelog: "Fixed bugs". This assumes a Fastfile with the lane defined and env var set.
2. Manage Provisioning and Archive: Run fastlane match adhoc to fetch profiles, then archive: xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive. Export with: xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportOptionsPlist ExportOptions.plist. Use in a workflow for ad-hoc distribution.

Graph Relationships

• Related to: mobile cluster (e.g., android-deploy skill for cross-platform deployment).
• Connected via: deployment tag (links to general deployment skills like ci-cd).
• Associated with: fastlane and ios tags (e.g., relates to fastlane-specific tools and other iOS skills).
• Dependencies: appstore tag implies integration with skills handling API keys and authentication.