What would you like to do?

1. Build a new app
2. Debug an existing app
3. Add a feature
4. Write/run tests
5. Optimize performance
6. Ship/release
7. Something else

Then read the matching workflow from workflows/ and follow it.

<verification_loop>

After Every Change

# 1. Does it build?
xcodebuild -scheme AppName -destination 'platform=iOS Simulator,name=iPhone 16' build 2>&1 | xcsift

# 2. Do tests pass?
xcodebuild -scheme AppName -destination 'platform=iOS Simulator,name=iPhone 16' test

# 3. Does it launch? (if UI changed)
xcrun simctl boot "iPhone 16" 2>/dev/null || true
xcrun simctl install booted ./build/Build/Products/Debug-iphonesimulator/AppName.app
xcrun simctl launch booted com.company.AppName

Report to the user:

• “Build: ✓”
• “Tests: 12 pass, 0 fail”
• “App launches in simulator, ready for you to check [specific thing]” </verification_loop>

<when_to_test>

Testing Decision

Write a test when:

• Logic that must be correct (calculations, transformations, rules)
• State changes (add, delete, update operations)
• Edge cases that could break (nil, empty, boundaries)
• Bug fix (test reproduces bug, then proves it’s fixed)
• Refactoring (tests prove behavior unchanged)

Skip tests when:

• Pure UI exploration (“make it blue and see if I like it”)
• Rapid prototyping (“just get something on screen”)
• Subjective quality (“does this feel right?”)
• One-off verification (launch and check manually)

The principle: Tests let the user verify correctness without reading code. If the user needs to verify it works, and it’s not purely visual, write a test. </when_to_test>

<reference_index>

Domain Knowledge

All in references/:

Architecture: app-architecture, swiftui-patterns, navigation-patterns Data: data-persistence, networking Platform Features: push-notifications, storekit, background-tasks Quality: polish-and-ux, accessibility, performance Assets & Security: app-icons, security, app-store Development: project-scaffolding, cli-workflow, cli-observability, testing, ci-cd </reference_index>

<workflows_index>

Workflows

All in workflows/:

Reference: Accessibility

Accessibility

VoiceOver, Dynamic Type, and inclusive design for iOS apps.

VoiceOver Support

Basic Labels

struct ItemRow: View {
    let item: Item

    var body: some View {
        HStack {
            Image(systemName: item.icon)
                .accessibilityHidden(true)  // Icon is decorative

            VStack(alignment: .leading) {
                Text(item.name)
                Text(item.date, style: .date)
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }

            Spacer()

            if item.isCompleted {
                Image(systemName: "checkmark")
                    .accessibilityHidden(true)
            }
        }
        .accessibilityElement(children: .combine)
        .accessibilityLabel("\(item.name), \(item.isCompleted ? "completed" : "incomplete")")
        .accessibilityHint("Double tap to view details")
    }
}

Custom Actions

struct ItemRow: View {
    let item: Item
    let onDelete: () -> Void
    let onToggle: () -> Void

    var body: some View {
        HStack {
            Text(item.name)
        }
        .accessibilityElement(children: .combine)
        .accessibilityLabel(item.name)
        .accessibilityAction(named: "Toggle completion") {
            onToggle()
        }
        .accessibilityAction(named: "Delete") {
            onDelete()
        }
    }
}

Traits

Text("Important Notice")
    .accessibilityAddTraits(.isHeader)

Button("Submit") { }
    .accessibilityAddTraits(.startsMediaSession)

Image("photo")
    .accessibilityAddTraits(.isImage)

Link("Learn more", destination: url)
    .accessibilityAddTraits(.isLink)

Toggle("Enable", isOn: $isEnabled)
    .accessibilityAddTraits(isEnabled ? .isSelected : [])

Announcements

// Announce changes
func saveCompleted() {
    AccessibilityNotification.Announcement("Item saved successfully").post()
}

// Screen change
func showNewScreen() {
    AccessibilityNotification.ScreenChanged(nil).post()
}

// Layout change
func expandSection() {
    isExpanded = true
    AccessibilityNotification.LayoutChanged(nil).post()
}

Rotor Actions

struct ArticleView: View {
    @State private var fontSize: CGFloat = 16

    var body: some View {
        Text(article.content)
            .font(.system(size: fontSize))
            .accessibilityAdjustableAction { direction in
                switch direction {
                case .increment:
                    fontSize = min(fontSize + 2, 32)
                case .decrement:
                    fontSize = max(fontSize - 2, 12)
                @unknown default:
                    break
                }
            }
    }
}

Dynamic Type

Scaled Fonts

// System fonts scale automatically
Text("Title")
    .font(.title)

Text("Body")
    .font(.body)

// Custom fonts with scaling
Text("Custom")
    .font(.custom("Helvetica", size: 17, relativeTo: .body))

// Fixed size (use sparingly)
Text("Fixed")
    .font(.system(size: 12).fixed())

Scaled Metrics

struct IconButton: View {
    @ScaledMetric var iconSize: CGFloat = 24
    @ScaledMetric(relativeTo: .body) var spacing: CGFloat = 8

    var body: some View {
        HStack(spacing: spacing) {
            Image(systemName: "star")
                .font(.system(size: iconSize))
            Text("Favorite")
        }
    }
}

Line Limits with Accessibility

Text(item.description)
    .lineLimit(3)
    .truncationMode(.tail)
    // But allow more for accessibility sizes
    .dynamicTypeSize(...DynamicTypeSize.accessibility1)

Testing Dynamic Type

#Preview("Default") {
    ContentView()
}

#Preview("Large") {
    ContentView()
        .environment(\.sizeCategory, .accessibilityLarge)
}

#Preview("Extra Extra Large") {
    ContentView()
        .environment(\.sizeCategory, .accessibilityExtraExtraLarge)
}

Reduce Motion

struct AnimatedView: View {
    @Environment(\.accessibilityReduceMotion) private var reduceMotion
    @State private var isExpanded = false

    var body: some View {
        VStack {
            // Content
        }
        .animation(reduceMotion ? .none : .spring(), value: isExpanded)
    }
}

// Alternative animations
struct TransitionView: View {
    @Environment(\.accessibilityReduceMotion) private var reduceMotion
    @State private var showDetail = false

    var body: some View {
        VStack {
            if showDetail {
                DetailView()
                    .transition(reduceMotion ? .opacity : .slide)
            }
        }
        .animation(.default, value: showDetail)
    }
}

Color and Contrast

Semantic Colors

// Use semantic colors that adapt
Text("Primary")
    .foregroundStyle(.primary)

Text("Secondary")
    .foregroundStyle(.secondary)

Text("Tertiary")
    .foregroundStyle(.tertiary)

// Error state
Text("Error")
    .foregroundStyle(.red)  // Use semantic red, not custom

Increase Contrast

struct ContrastAwareView: View {
    @Environment(\.accessibilityDifferentiateWithoutColor) private var differentiateWithoutColor
    @Environment(\.accessibilityIncreaseContrast) private var increaseContrast

    var body: some View {
        HStack {
            Circle()
                .fill(increaseContrast ? .primary : .secondary)

            if differentiateWithoutColor {
                // Add non-color indicator
                Image(systemName: "checkmark")
            }
        }
    }
}

Color Blind Support

struct StatusIndicator: View {
    let status: Status
    @Environment(\.accessibilityDifferentiateWithoutColor) private var differentiateWithoutColor

    var body: some View {
        HStack {
            Circle()
                .fill(status.color)
                .frame(width: 10, height: 10)

            if differentiateWithoutColor {
                Image(systemName: status.icon)
            }

            Text(status.label)
        }
    }
}

enum Status {
    case success, warning, error

    var color: Color {
        switch self {
        case .success: return .green
        case .warning: return .orange
        case .error: return .red
        }
    }

    var icon: String {
        switch self {
        case .success: return "checkmark.circle"
        case .warning: return "exclamationmark.triangle"
        case .error: return "xmark.circle"
        }
    }

    var label: String {
        switch self {
        case .success: return "Success"
        case .warning: return "Warning"
        case .error: return "Error"
        }
    }
}

Focus Management

Focus State

struct LoginView: View {
    @State private var username = ""
    @State private var password = ""
    @FocusState private var focusedField: Field?

    enum Field {
        case username, password
    }

    var body: some View {
        Form {
            TextField("Username", text: $username)
                .focused($focusedField, equals: .username)
                .submitLabel(.next)
                .onSubmit {
                    focusedField = .password
                }

            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)
                .submitLabel(.done)
                .onSubmit {
                    login()
                }
        }
        .onAppear {
            focusedField = .username
        }
    }
}

Accessibility Focus

struct AlertView: View {
    @AccessibilityFocusState private var isAlertFocused: Bool

    var body: some View {
        VStack {
            Text("Important Alert")
                .accessibilityFocused($isAlertFocused)
        }
        .onAppear {
            isAlertFocused = true
        }
    }
}

Button Shapes

struct AccessibleButton: View {
    @Environment(\.accessibilityShowButtonShapes) private var showButtonShapes

    var body: some View {
        Button("Action") { }
            .padding()
            .background(showButtonShapes ? Color.accentColor.opacity(0.1) : Color.clear)
            .clipShape(RoundedRectangle(cornerRadius: 8))
    }
}

Smart Invert Colors

Image("photo")
    .accessibilityIgnoresInvertColors()  // Photos shouldn't invert

Audit Checklist

VoiceOver

• All interactive elements have labels
• Decorative elements are hidden
• Custom actions for swipe gestures
• Headings marked correctly
• Announcements for dynamic changes

Dynamic Type

• All text uses dynamic fonts
• Layout adapts to large sizes
• No text truncation at accessibility sizes
• Touch targets remain accessible (44pt minimum)

Color and Contrast

• 4.5:1 contrast ratio for text
• Information not conveyed by color alone
• Works with Increase Contrast
• Works with Smart Invert

Motion

• Animations respect Reduce Motion
• No auto-playing animations
• Alternative interactions for gesture-only features

General

• All functionality available via VoiceOver
• Logical focus order
• Error messages are accessible
• Time limits are adjustable

Testing Tools

Accessibility Inspector

1. Open Xcode > Open Developer Tool > Accessibility Inspector
2. Point at elements to inspect labels, traits, hints
3. Run audit for common issues

VoiceOver Practice

1. Settings > Accessibility > VoiceOver
2. Use with your app
3. Navigate by swiping, double-tap to activate

Voice Control

1. Settings > Accessibility > Voice Control
2. Test all interactions with voice commands

Xcode Previews

#Preview {
    ContentView()
        .environment(\.sizeCategory, .accessibilityExtraExtraExtraLarge)
        .environment(\.accessibilityReduceMotion, true)
        .environment(\.accessibilityDifferentiateWithoutColor, true)
}

Reference: App Architecture

App Architecture

State management, dependency injection, and architectural patterns for iOS apps.

State Management

@Observable (iOS 17+)

The modern approach for shared state:

@Observable
class AppState {
    var items: [Item] = []
    var selectedItemID: UUID?
    var isLoading = false
    var error: AppError?

    // Computed properties work naturally
    var selectedItem: Item? {
        items.first { $0.id == selectedItemID }
    }

    var hasItems: Bool { !items.isEmpty }
}

// In views - only re-renders when used properties change
struct ContentView: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        if appState.isLoading {
            ProgressView()
        } else {
            ItemList(items: appState.items)
        }
    }
}

Two-Way Bindings

For binding to @Observable properties:

struct SettingsView: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        @Bindable var appState = appState

        Form {
            TextField("Username", text: $appState.username)
            Toggle("Notifications", isOn: $appState.notificationsEnabled)
        }
    }
}

State Decision Tree

@State - View-local UI state

• Toggle expanded/collapsed
• Text field content
• Sheet presentation

struct ItemRow: View {
    @State private var isExpanded = false

    var body: some View {
        VStack {
            // ...
        }
    }
}

@Observable in Environment - Shared app state

• User session
• Navigation state
• Feature flags

@main
struct MyApp: App {
    @State private var appState = AppState()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(appState)
        }
    }
}

@Query - SwiftData persistence

• Database entities
• Filtered/sorted queries

struct ItemList: View {
    @Query(sort: \Item.createdAt, order: .reverse)
    private var items: [Item]

    var body: some View {
        List(items) { item in
            ItemRow(item: item)
        }
    }
}

Dependency Injection

Environment Keys

Define environment keys for testable dependencies:

// Protocol for testability
protocol NetworkServiceProtocol {
    func fetch<T: Decodable>(_ endpoint: Endpoint) async throws -> T
}

// Live implementation
class LiveNetworkService: NetworkServiceProtocol {
    func fetch<T: Decodable>(_ endpoint: Endpoint) async throws -> T {
        // Real implementation
    }
}

// Mock for testing
class MockNetworkService: NetworkServiceProtocol {
    var mockResult: Any?
    var mockError: Error?

    func fetch<T: Decodable>(_ endpoint: Endpoint) async throws -> T {
        if let error = mockError { throw error }
        return mockResult as! T
    }
}

// Environment key
struct NetworkServiceKey: EnvironmentKey {
    static let defaultValue: NetworkServiceProtocol = LiveNetworkService()
}

extension EnvironmentValues {
    var networkService: NetworkServiceProtocol {
        get { self[NetworkServiceKey.self] }
        set { self[NetworkServiceKey.self] = newValue }
    }
}

// Inject at app level
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.networkService, LiveNetworkService())
        }
    }
}

// Use in views
struct ItemList: View {
    @Environment(\.networkService) private var networkService

    var body: some View {
        // ...
    }

    func loadItems() async {
        let items: [Item] = try await networkService.fetch(.items)
    }
}

Dependency Container

For complex apps with many dependencies:

@Observable
class AppDependencies {
    let network: NetworkServiceProtocol
    let storage: StorageServiceProtocol
    let purchases: PurchaseServiceProtocol
    let analytics: AnalyticsServiceProtocol

    init(
        network: NetworkServiceProtocol = LiveNetworkService(),
        storage: StorageServiceProtocol = LiveStorageService(),
        purchases: PurchaseServiceProtocol = LivePurchaseService(),
        analytics: AnalyticsServiceProtocol = LiveAnalyticsService()
    ) {
        self.network = network
        self.storage = storage
        self.purchases = purchases
        self.analytics = analytics
    }

    // Convenience for testing
    static func mock() -> AppDependencies {
        AppDependencies(
            network: MockNetworkService(),
            storage: MockStorageService(),
            purchases: MockPurchaseService(),
            analytics: MockAnalyticsService()
        )
    }
}

// Inject as single environment object
@main
struct MyApp: App {
    @State private var dependencies = AppDependencies()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(dependencies)
        }
    }
}

View Models (When Needed)

For views with significant logic, use a view-local model:

struct ItemDetailScreen: View {
    let itemID: UUID
    @State private var viewModel: ItemDetailViewModel

    init(itemID: UUID) {
        self.itemID = itemID
        self._viewModel = State(initialValue: ItemDetailViewModel(itemID: itemID))
    }

    var body: some View {
        Form {
            if viewModel.isLoading {
                ProgressView()
            } else if let item = viewModel.item {
                ItemContent(item: item)
            }
        }
        .task {
            await viewModel.load()
        }
    }
}

@Observable
class ItemDetailViewModel {
    let itemID: UUID
    var item: Item?
    var isLoading = false
    var error: Error?

    init(itemID: UUID) {
        self.itemID = itemID
    }

    func load() async {
        isLoading = true
        defer { isLoading = false }

        do {
            item = try await fetchItem(id: itemID)
        } catch {
            self.error = error
        }
    }

    func save() async {
        // Save logic
    }
}

Coordinator Pattern

For complex navigation flows:

@Observable
class OnboardingCoordinator {
    var currentStep: OnboardingStep = .welcome
    var isComplete = false

    enum OnboardingStep {
        case welcome
        case permissions
        case personalInfo
        case complete
    }

    func next() {
        switch currentStep {
        case .welcome:
            currentStep = .permissions
        case .permissions:
            currentStep = .personalInfo
        case .personalInfo:
            currentStep = .complete
            isComplete = true
        case .complete:
            break
        }
    }

    func back() {
        switch currentStep {
        case .welcome:
            break
        case .permissions:
            currentStep = .welcome
        case .personalInfo:
            currentStep = .permissions
        case .complete:
            currentStep = .personalInfo
        }
    }
}

struct OnboardingFlow: View {
    @State private var coordinator = OnboardingCoordinator()

    var body: some View {
        Group {
            switch coordinator.currentStep {
            case .welcome:
                WelcomeView(onContinue: coordinator.next)
            case .permissions:
                PermissionsView(onContinue: coordinator.next, onBack: coordinator.back)
            case .personalInfo:
                PersonalInfoView(onContinue: coordinator.next, onBack: coordinator.back)
            case .complete:
                CompletionView()
            }
        }
        .animation(.default, value: coordinator.currentStep)
    }
}

Error Handling

Structured Error Types

enum AppError: LocalizedError {
    case networkError(NetworkError)
    case storageError(StorageError)
    case validationError(String)
    case unauthorized
    case unknown(Error)

    var errorDescription: String? {
        switch self {
        case .networkError(let error):
            return error.localizedDescription
        case .storageError(let error):
            return error.localizedDescription
        case .validationError(let message):
            return message
        case .unauthorized:
            return "Please sign in to continue"
        case .unknown(let error):
            return error.localizedDescription
        }
    }

    var recoverySuggestion: String? {
        switch self {
        case .networkError:
            return "Check your internet connection and try again"
        case .unauthorized:
            return "Tap to sign in"
        default:
            return nil
        }
    }
}

enum NetworkError: LocalizedError {
    case noConnection
    case timeout
    case serverError(Int)
    case decodingError

    var errorDescription: String? {
        switch self {
        case .noConnection:
            return "No internet connection"
        case .timeout:
            return "Request timed out"
        case .serverError(let code):
            return "Server error (\(code))"
        case .decodingError:
            return "Invalid response from server"
        }
    }
}

Error Presentation

struct ContentView: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        NavigationStack {
            // Content
        }
        .alert(
            "Error",
            isPresented: Binding(
                get: { appState.error != nil },
                set: { if !$0 { appState.error = nil } }
            ),
            presenting: appState.error
        ) { error in
            Button("OK") { }
            if error.recoverySuggestion != nil {
                Button("Retry") {
                    Task { await retry() }
                }
            }
        } message: { error in
            VStack {
                Text(error.localizedDescription)
                if let suggestion = error.recoverySuggestion {
                    Text(suggestion)
                        .font(.caption)
                }
            }
        }
    }
}

Testing Architecture

Unit Testing with Mocks

@Test
func testLoadItems() async throws {
    // Arrange
    let mockNetwork = MockNetworkService()
    mockNetwork.mockResult = [Item(name: "Test")]

    let viewModel = ItemListViewModel(networkService: mockNetwork)

    // Act
    await viewModel.load()

    // Assert
    #expect(viewModel.items.count == 1)
    #expect(viewModel.items[0].name == "Test")
    #expect(viewModel.isLoading == false)
}

@Test
func testLoadItemsError() async throws {
    // Arrange
    let mockNetwork = MockNetworkService()
    mockNetwork.mockError = NetworkError.noConnection

    let viewModel = ItemListViewModel(networkService: mockNetwork)

    // Act
    await viewModel.load()

    // Assert
    #expect(viewModel.items.isEmpty)
    #expect(viewModel.error != nil)
}

Preview with Dependencies

#Preview {
    ContentView()
        .environment(AppDependencies.mock())
        .environment(AppState())
}

Reference: App Icons

App Icons

Complete guide for generating, configuring, and managing iOS app icons from the CLI.

Quick Start (Xcode 14+)

The simplest approach—provide a single 1024×1024 PNG and let Xcode auto-generate all sizes:

1. Create Assets.xcassets/AppIcon.appiconset/
2. Add your 1024×1024 PNG
3. Create Contents.json with single-size configuration

{
  "images": [
    {
      "filename": "icon-1024.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    }
  ],
  "info": {
    "author": "xcode",
    "version": 1
  }
}

The system auto-generates all required device sizes from this single image.

CLI Icon Generation

Using sips (Built into macOS)

Generate all required sizes from a 1024×1024 source:

#!/bin/bash
# generate-app-icons.sh
# Usage: ./generate-app-icons.sh source.png output-dir

SOURCE="$1"
OUTPUT="${2:-AppIcon.appiconset}"

mkdir -p "$OUTPUT"

# Generate all required sizes
sips -z 1024 1024 "$SOURCE" --out "$OUTPUT/icon-1024.png"
sips -z 180 180 "$SOURCE" --out "$OUTPUT/icon-180.png"
sips -z 167 167 "$SOURCE" --out "$OUTPUT/icon-167.png"
sips -z 152 152 "$SOURCE" --out "$OUTPUT/icon-152.png"
sips -z 120 120 "$SOURCE" --out "$OUTPUT/icon-120.png"
sips -z 87 87 "$SOURCE" --out "$OUTPUT/icon-87.png"
sips -z 80 80 "$SOURCE" --out "$OUTPUT/icon-80.png"
sips -z 76 76 "$SOURCE" --out "$OUTPUT/icon-76.png"
sips -z 60 60 "$SOURCE" --out "$OUTPUT/icon-60.png"
sips -z 58 58 "$SOURCE" --out "$OUTPUT/icon-58.png"
sips -z 40 40 "$SOURCE" --out "$OUTPUT/icon-40.png"
sips -z 29 29 "$SOURCE" --out "$OUTPUT/icon-29.png"
sips -z 20 20 "$SOURCE" --out "$OUTPUT/icon-20.png"

echo "Generated icons in $OUTPUT"

Using ImageMagick

#!/bin/bash
# Requires: brew install imagemagick

SOURCE="$1"
OUTPUT="${2:-AppIcon.appiconset}"

mkdir -p "$OUTPUT"

for size in 1024 180 167 152 120 87 80 76 60 58 40 29 20; do
  convert "$SOURCE" -resize "${size}x${size}!" "$OUTPUT/icon-$size.png"
done

Complete Contents.json (All Sizes)

For manual size control or when not using single-size mode:

{
  "images": [
    {
      "filename": "icon-1024.png",
      "idiom": "ios-marketing",
      "scale": "1x",
      "size": "1024x1024"
    },
    {
      "filename": "icon-180.png",
      "idiom": "iphone",
      "scale": "3x",
      "size": "60x60"
    },
    {
      "filename": "icon-120.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "60x60"
    },
    {
      "filename": "icon-87.png",
      "idiom": "iphone",
      "scale": "3x",
      "size": "29x29"
    },
    {
      "filename": "icon-58.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "29x29"
    },
    {
      "filename": "icon-120.png",
      "idiom": "iphone",
      "scale": "3x",
      "size": "40x40"
    },
    {
      "filename": "icon-80.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "40x40"
    },
    {
      "filename": "icon-60.png",
      "idiom": "iphone",
      "scale": "3x",
      "size": "20x20"
    },
    {
      "filename": "icon-40.png",
      "idiom": "iphone",
      "scale": "2x",
      "size": "20x20"
    },
    {
      "filename": "icon-167.png",
      "idiom": "ipad",
      "scale": "2x",
      "size": "83.5x83.5"
    },
    {
      "filename": "icon-152.png",
      "idiom": "ipad",
      "scale": "2x",
      "size": "76x76"
    },
    {
      "filename": "icon-76.png",
      "idiom": "ipad",
      "scale": "1x",
      "size": "76x76"
    },
    {
      "filename": "icon-80.png",
      "idiom": "ipad",
      "scale": "2x",
      "size": "40x40"
    },
    {
      "filename": "icon-40.png",
      "idiom": "ipad",
      "scale": "1x",
      "size": "40x40"
    },
    {
      "filename": "icon-58.png",
      "idiom": "ipad",
      "scale": "2x",
      "size": "29x29"
    },
    {
      "filename": "icon-29.png",
      "idiom": "ipad",
      "scale": "1x",
      "size": "29x29"
    },
    {
      "filename": "icon-40.png",
      "idiom": "ipad",
      "scale": "2x",
      "size": "20x20"
    },
    {
      "filename": "icon-20.png",
      "idiom": "ipad",
      "scale": "1x",
      "size": "20x20"
    }
  ],
  "info": {
    "author": "xcode",
    "version": 1
  }
}

Required Sizes Reference

iOS 18 Dark Mode & Tinted Icons

iOS 18 adds appearance variants: Any (default), Dark, and Tinted.

Asset Structure

Create three versions of each icon:

• icon-1024.png - Standard (Any appearance)
• icon-1024-dark.png - Dark mode variant
• icon-1024-tinted.png - Tinted variant

Dark Mode Design

• Use transparent background (system provides dark fill)
• Keep foreground elements recognizable
• Lighten foreground colors for contrast against dark background
• Or provide full icon with dark-tinted background

Tinted Design

• Must be grayscale, fully opaque
• System applies user’s tint color over the grayscale
• Use gradient background: #313131 (top) to #141414 (bottom)

Contents.json with Appearances

{
  "images": [
    {
      "filename": "icon-1024.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    },
    {
      "appearances": [
        {
          "appearance": "luminosity",
          "value": "dark"
        }
      ],
      "filename": "icon-1024-dark.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    },
    {
      "appearances": [
        {
          "appearance": "luminosity",
          "value": "tinted"
        }
      ],
      "filename": "icon-1024-tinted.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    }
  ],
  "info": {
    "author": "xcode",
    "version": 1
  }
}

Alternate App Icons

Allow users to choose between different app icons.

Setup

1. Add alternate icon sets to asset catalog
2. Configure build setting in project.pbxproj:

ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES = "DarkIcon ColorfulIcon";

Or add icons loose in project with @2x/@3x naming and configure Info.plist:

<key>CFBundleIcons</key>
<dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>DarkIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>DarkIcon</string>
            </array>
        </dict>
        <key>ColorfulIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>ColorfulIcon</string>
            </array>
        </dict>
    </dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon</string>
        </array>
    </dict>
</dict>

SwiftUI Implementation

import SwiftUI

enum AppIcon: String, CaseIterable, Identifiable {
    case primary = "AppIcon"
    case dark = "DarkIcon"
    case colorful = "ColorfulIcon"

    var id: String { rawValue }

    var displayName: String {
        switch self {
        case .primary: return "Default"
        case .dark: return "Dark"
        case .colorful: return "Colorful"
        }
    }

    var iconName: String? {
        self == .primary ? nil : rawValue
    }
}

@Observable
class IconManager {
    var currentIcon: AppIcon = .primary

    init() {
        if let iconName = UIApplication.shared.alternateIconName,
           let icon = AppIcon(rawValue: iconName) {
            currentIcon = icon
        }
    }

    func setIcon(_ icon: AppIcon) async throws {
        guard UIApplication.shared.supportsAlternateIcons else {
            throw IconError.notSupported
        }

        try await UIApplication.shared.setAlternateIconName(icon.iconName)
        currentIcon = icon
    }

    enum IconError: LocalizedError {
        case notSupported

        var errorDescription: String? {
            "This device doesn't support alternate icons"
        }
    }
}

struct IconPickerView: View {
    @Environment(IconManager.self) private var iconManager
    @State private var error: Error?

    var body: some View {
        List(AppIcon.allCases) { icon in
            Button {
                Task {
                    do {
                        try await iconManager.setIcon(icon)
                    } catch {
                        self.error = error
                    }
                }
            } label: {
                HStack {
                    // Preview image (add to asset catalog)
                    Image("\(icon.rawValue)-preview")
                        .resizable()
                        .frame(width: 60, height: 60)
                        .clipShape(RoundedRectangle(cornerRadius: 12))

                    Text(icon.displayName)

                    Spacer()

                    if iconManager.currentIcon == icon {
                        Image(systemName: "checkmark")
                            .foregroundStyle(.blue)
                    }
                }
            }
            .buttonStyle(.plain)
        }
        .navigationTitle("App Icon")
        .alert("Error", isPresented: .constant(error != nil)) {
            Button("OK") { error = nil }
        } message: {
            if let error {
                Text(error.localizedDescription)
            }
        }
    }
}

Design Guidelines

Technical Requirements

• Format: PNG, non-interlaced
• Transparency: Not allowed (fully opaque)
• Shape: Square with 90° corners
• Color Space: sRGB or Display P3
• Minimum: 1024×1024 for App Store

Design Constraints

1. No rounded corners - System applies mask automatically
2. No text unless essential to brand identity
3. No photos or screenshots - Too detailed at small sizes
4. No drop shadows or gloss - System may add effects
5. No Apple hardware - Copyright protected
6. No SF Symbols - Prohibited in icons/logos

Safe Zone

The system mask cuts corners using a superellipse shape. Keep critical elements away from edges.

Corner radius formula: 10/57 × icon_size

• 57px icon = 10px radius
• 1024px icon ≈ 180px radius

Test at Small Sizes

Your icon must be recognizable at 29×29 pixels (Settings icon size). If details are lost, simplify the design.

Troubleshooting

”Missing Marketing Icon” Error

Ensure you have a 1024×1024 icon with idiom ios-marketing in Contents.json.

Icon Has Transparency

App Store rejects icons with alpha channels. Check with:

sips -g hasAlpha icon-1024.png

Remove alpha channel:

sips -s format png -s formatOptions 0 icon-1024.png --out icon-1024-opaque.png

Or with ImageMagick:

convert icon-1024.png -background white -alpha remove -alpha off icon-1024-opaque.png

Interlaced PNG Error

Convert to non-interlaced:

convert icon-1024.png -interlace none icon-1024.png

Rounded Corners Look Wrong

Never pre-round your icon. Provide square corners and let iOS apply the mask. Pre-rounding causes visual artifacts where the mask doesn’t align.

Complete Generation Script

One-command generation for a new project:

#!/bin/bash
# setup-app-icon.sh
# Usage: ./setup-app-icon.sh source.png project-path

SOURCE="$1"
PROJECT="${2:-.}"
ICONSET="$PROJECT/Assets.xcassets/AppIcon.appiconset"

mkdir -p "$ICONSET"

# Generate 1024x1024 (single-size mode)
sips -z 1024 1024 "$SOURCE" --out "$ICONSET/icon-1024.png"

# Remove alpha channel if present
sips -s format png -s formatOptions 0 "$ICONSET/icon-1024.png" --out "$ICONSET/icon-1024.png"

# Generate Contents.json for single-size mode
cat > "$ICONSET/Contents.json" << 'EOF'
{
  "images": [
    {
      "filename": "icon-1024.png",
      "idiom": "universal",
      "platform": "ios",
      "size": "1024x1024"
    }
  ],
  "info": {
    "author": "xcode",
    "version": 1
  }
}
EOF

echo "App icon configured at $ICONSET"

Reference: App Store

App Store Submission

App Review guidelines, privacy requirements, and submission checklist.

Pre-Submission Checklist

App Completion

• All features working
• No crashes or major bugs
• Performance optimized
• Memory leaks resolved

Content Requirements

• App icon (1024x1024)
• Screenshots for all device sizes
• App preview videos (optional)
• Description and keywords
• Privacy policy URL
• Support URL

Technical Requirements

• Minimum iOS version set correctly
• Privacy manifest (PrivacyInfo.xcprivacy)
• All permissions have usage descriptions
• Export compliance answered
• Content rights declared

Screenshots

Required Sizes

iPhone 6.9" (iPhone 16 Pro Max): 1320 x 2868
iPhone 6.7" (iPhone 15 Plus): 1290 x 2796
iPhone 6.5" (iPhone 11 Pro Max): 1284 x 2778
iPhone 5.5" (iPhone 8 Plus): 1242 x 2208

iPad Pro 13" (6th gen): 2064 x 2752
iPad Pro 12.9" (2nd gen): 2048 x 2732

Automating Screenshots

With fastlane:

# Fastfile
lane :screenshots do
  capture_screenshots(
    scheme: "MyAppUITests",
    devices: [
      "iPhone 16 Pro Max",
      "iPhone 8 Plus",
      "iPad Pro (12.9-inch) (6th generation)"
    ],
    languages: ["en-US", "es-ES"],
    output_directory: "./screenshots"
  )
end

Snapfile:

devices([
  "iPhone 16 Pro Max",
  "iPhone 8 Plus",
  "iPad Pro (12.9-inch) (6th generation)"
])

languages(["en-US"])
scheme("MyAppUITests")
output_directory("./screenshots")
clear_previous_screenshots(true)

UI Test for screenshots:

import XCTest

class ScreenshotTests: XCTestCase {
    override func setUpWithError() throws {
        continueAfterFailure = false
        let app = XCUIApplication()
        setupSnapshot(app)
        app.launch()
    }

    func testScreenshots() {
        snapshot("01-HomeScreen")

        // Navigate to feature
        app.buttons["Feature"].tap()
        snapshot("02-FeatureScreen")

        // Show detail
        app.cells.firstMatch.tap()
        snapshot("03-DetailScreen")
    }
}

Privacy Policy

Required Elements

1. What data is collected
2. How it’s used
3. Who it’s shared with
4. How long it’s retained
5. User rights (access, deletion)
6. Contact information

Template Structure

# Privacy Policy for [App Name]

Last updated: [Date]

## Information We Collect
- Account information (email, name)
- Usage data (features used, session duration)

## How We Use Information
- Provide app functionality
- Improve user experience
- Send notifications (with permission)

## Data Sharing
We do not sell your data. We share with:
- Analytics providers (anonymized)
- Cloud storage providers

## Data Retention
We retain data while your account is active.
Request deletion at [email].

## Your Rights
- Access your data
- Request deletion
- Export your data

## Contact
[email]

App Review Guidelines

Common Rejections

1. Incomplete Information

• Missing demo account credentials
• Unclear functionality

2. Bugs and Crashes

• App crashes on launch
• Features don’t work

3. Placeholder Content

• Lorem ipsum text
• Incomplete UI

4. Privacy Issues

• Missing usage descriptions
• Accessing data without permission

5. Misleading Metadata

• Screenshots don’t match app
• Description claims unavailable features

Demo Account

In App Store Connect notes:

Demo Account:
Username: [email protected]
Password: Demo123!

Notes:
- Subscription features are enabled
- Push notifications require real device

Review Notes

Notes for Review:

1. This app requires camera access for QR scanning (Settings tab > Scan QR).

2. Push notifications are used for:
   - Order status updates
   - New message alerts

3. Background location is used for:
   - Delivery tracking only when order is active

4. Demo account has pre-populated data for testing.

5. In-app purchases can be tested with sandbox account.

Export Compliance

Quick Check

Answer YES to export compliance if your app:

• Only uses HTTPS for network requests
• Only uses Apple’s standard encryption APIs
• Only uses encryption for authentication/DRM

Most apps using HTTPS only can answer YES and select that encryption is exempt.

Full Compliance

If using custom encryption, you need:

• Encryption Registration Number (ERN) from BIS
• Or exemption documentation

App Privacy Labels

In App Store Connect, declare:

Data Types

• Contact Info (name, email, phone)
• Health & Fitness
• Financial Info
• Location
• Browsing History
• Search History
• Identifiers (user ID, device ID)
• Usage Data
• Diagnostics

Data Use

For each data type:

• Linked to User: Can identify the user
• Used for Tracking: Cross-app/web advertising

Example Declaration

Contact Info - Email Address:
- Used for: App Functionality (account creation)
- Linked to User: Yes
- Used for Tracking: No

Usage Data:
- Used for: Analytics
- Linked to User: No
- Used for Tracking: No

In-App Purchases

Configuration

1. App Store Connect > Features > In-App Purchases
2. Create products with:
   • Reference name
   • Product ID (com.app.product)
   • Price
   • Localized display name/description

Review Screenshots

Provide screenshots showing:

• Purchase screen
• Content being purchased
• Restore purchases option

Subscription Guidelines

• Clear pricing shown before purchase
• Easy cancellation instructions
• Terms of service link
• Restore purchases available

TestFlight

Internal Testing

• Up to 100 internal testers
• No review required
• Immediate availability

External Testing

• Up to 10,000 testers
• Beta App Review required
• Public link option

Test Notes

What to Test:
- New feature: Cloud sync
- Bug fix: Login issues on iOS 18
- Performance improvements

Known Issues:
- Widget may not update immediately
- Dark mode icon pending

Submission Process

1. Archive

xcodebuild archive \
    -project MyApp.xcodeproj \
    -scheme MyApp \
    -archivePath build/MyApp.xcarchive

2. Export

xcodebuild -exportArchive \
    -archivePath build/MyApp.xcarchive \
    -exportOptionsPlist ExportOptions.plist \
    -exportPath build/

3. Upload

xcrun altool --upload-app \
    --type ios \
    --file build/MyApp.ipa \
    --apiKey YOUR_KEY_ID \
    --apiIssuer YOUR_ISSUER_ID

4. Submit

1. App Store Connect > Select build
2. Complete all metadata
3. Submit for Review

Post-Submission

Review Timeline

• Average: 24-48 hours
• First submission: May take longer
• Complex apps: May need more review

Responding to Rejection

1. Read rejection carefully
2. Address ALL issues
3. Reply in Resolution Center
4. Resubmit

Expedited Review

Request for:

• Critical bug fixes
• Time-sensitive events
• Security issues

Submit request at: https://developer.apple.com/contact/app-store/?topic=expedite

Phased Release

After approval, choose:

• Immediate: Available to everyone
• Phased: 7 days gradual rollout
  • Day 1: 1%
  • Day 2: 2%
  • Day 3: 5%
  • Day 4: 10%
  • Day 5: 20%
  • Day 6: 50%
  • Day 7: 100%

Can pause or accelerate at any time.

Version Updates

What’s New

Version 2.1

New:
• Cloud sync across devices
• Dark mode support
• Widget for home screen

Improved:
• Faster app launch
• Better search results

Fixed:
• Login issues on iOS 18
• Notification sound not playing

Maintaining Multiple Versions

• Keep previous version available during review
• Test backward compatibility
• Consider forced updates for critical fixes

Reference: Background Tasks

Background Tasks

BGTaskScheduler, background fetch, and silent push for background processing.

BGTaskScheduler

Setup

1. Add capability: Background Modes
2. Enable: Background fetch, Background processing
3. Register identifiers in Info.plist:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.app.refresh</string>
    <string>com.app.processing</string>
</array>

Registration

import BackgroundTasks

@main
struct MyApp: App {
    init() {
        registerBackgroundTasks()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }

    private func registerBackgroundTasks() {
        // App Refresh - for frequent, short updates
        BGTaskScheduler.shared.register(
            forTaskWithIdentifier: "com.app.refresh",
            using: nil
        ) { task in
            guard let task = task as? BGAppRefreshTask else { return }
            handleAppRefresh(task: task)
        }

        // Processing - for longer, deferrable work
        BGTaskScheduler.shared.register(
            forTaskWithIdentifier: "com.app.processing",
            using: nil
        ) { task in
            guard let task = task as? BGProcessingTask else { return }
            handleProcessing(task: task)
        }
    }
}

App Refresh Task

Short tasks that need to run frequently:

func handleAppRefresh(task: BGAppRefreshTask) {
    // Schedule next refresh
    scheduleAppRefresh()

    // Create task
    let refreshTask = Task {
        do {
            try await syncLatestData()
            task.setTaskCompleted(success: true)
        } catch {
            task.setTaskCompleted(success: false)
        }
    }

    // Handle expiration
    task.expirationHandler = {
        refreshTask.cancel()
    }
}

func scheduleAppRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "com.app.refresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)  // 15 minutes

    do {
        try BGTaskScheduler.shared.submit(request)
    } catch {
        print("Could not schedule app refresh: \(error)")
    }
}

private func syncLatestData() async throws {
    // Fetch new data from server
    // Update local database
    // Badge update if needed
}

Processing Task

Longer tasks that can be deferred:

func handleProcessing(task: BGProcessingTask) {
    // Schedule next
    scheduleProcessing()

    let processingTask = Task {
        do {
            try await performHeavyWork()
            task.setTaskCompleted(success: true)
        } catch {
            task.setTaskCompleted(success: false)
        }
    }

    task.expirationHandler = {
        processingTask.cancel()
    }
}

func scheduleProcessing() {
    let request = BGProcessingTaskRequest(identifier: "com.app.processing")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 60 * 60)  // 1 hour
    request.requiresNetworkConnectivity = true
    request.requiresExternalPower = false

    do {
        try BGTaskScheduler.shared.submit(request)
    } catch {
        print("Could not schedule processing: \(error)")
    }
}

private func performHeavyWork() async throws {
    // Database maintenance
    // Large file uploads
    // ML model training
    // Cache cleanup
}

Background URLSession

For large uploads/downloads that continue when app is suspended:

class BackgroundDownloadService: NSObject {
    static let shared = BackgroundDownloadService()

    private lazy var session: URLSession = {
        let config = URLSessionConfiguration.background(
            withIdentifier: "com.app.background.download"
        )
        config.isDiscretionary = true  // System chooses best time
        config.sessionSendsLaunchEvents = true  // Wake app on completion

        return URLSession(
            configuration: config,
            delegate: self,
            delegateQueue: nil
        )
    }()

    private var completionHandler: (() -> Void)?

    func download(from url: URL) {
        let task = session.downloadTask(with: url)
        task.resume()
    }

    func handleEventsForBackgroundURLSession(
        identifier: String,
        completionHandler: @escaping () -> Void
    ) {
        self.completionHandler = completionHandler
    }
}

extension BackgroundDownloadService: URLSessionDownloadDelegate {
    func urlSession(
        _ session: URLSession,
        downloadTask: URLSessionDownloadTask,
        didFinishDownloadingTo location: URL
    ) {
        // Move file to permanent location
        let documentsURL = FileManager.default.urls(
            for: .documentDirectory,
            in: .userDomainMask
        ).first!
        let destinationURL = documentsURL.appendingPathComponent("downloaded.file")

        try? FileManager.default.moveItem(at: location, to: destinationURL)
    }

    func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
        DispatchQueue.main.async {
            self.completionHandler?()
            self.completionHandler = nil
        }
    }
}

// In AppDelegate
func application(
    _ application: UIApplication,
    handleEventsForBackgroundURLSession identifier: String,
    completionHandler: @escaping () -> Void
) {
    BackgroundDownloadService.shared.handleEventsForBackgroundURLSession(
        identifier: identifier,
        completionHandler: completionHandler
    )
}

Silent Push Notifications

Trigger background work from server:

Configuration

Entitlements:

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

Handling

// In AppDelegate
func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    guard let action = userInfo["action"] as? String else {
        return .noData
    }

    do {
        switch action {
        case "sync":
            try await syncData()
            return .newData
        case "refresh":
            try await refreshContent()
            return .newData
        default:
            return .noData
        }
    } catch {
        return .failed
    }
}

Payload

{
    "aps": {
        "content-available": 1
    },
    "action": "sync",
    "data": {
        "lastUpdate": "2025-01-01T00:00:00Z"
    }
}

Location Updates

Background location monitoring:

import CoreLocation

class LocationService: NSObject, CLLocationManagerDelegate {
    private let manager = CLLocationManager()

    override init() {
        super.init()
        manager.delegate = self
        manager.allowsBackgroundLocationUpdates = true
        manager.pausesLocationUpdatesAutomatically = true
    }

    // Significant location changes (battery efficient)
    func startMonitoringSignificantChanges() {
        manager.startMonitoringSignificantLocationChanges()
    }

    // Region monitoring
    func monitorRegion(_ region: CLCircularRegion) {
        manager.startMonitoring(for: region)
    }

    // Continuous updates (high battery usage)
    func startContinuousUpdates() {
        manager.desiredAccuracy = kCLLocationAccuracyBest
        manager.startUpdatingLocation()
    }

    func locationManager(
        _ manager: CLLocationManager,
        didUpdateLocations locations: [CLLocation]
    ) {
        guard let location = locations.last else { return }

        // Process location update
        Task {
            try? await uploadLocation(location)
        }
    }

    func locationManager(
        _ manager: CLLocationManager,
        didEnterRegion region: CLRegion
    ) {
        // Handle region entry
    }
}

Background Audio

For audio playback while app is in background:

import AVFoundation

class AudioService {
    private var player: AVAudioPlayer?

    func configureAudioSession() throws {
        let session = AVAudioSession.sharedInstance()
        try session.setCategory(.playback, mode: .default)
        try session.setActive(true)
    }

    func play(url: URL) throws {
        player = try AVAudioPlayer(contentsOf: url)
        player?.play()
    }
}

Testing Background Tasks

Simulate in Debugger

// Pause in debugger, then:
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.app.refresh"]

Force Early Execution

#if DEBUG
func debugScheduleRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "com.app.refresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 1)  // 1 second for testing

    try? BGTaskScheduler.shared.submit(request)
}
#endif

Best Practices

Battery Efficiency

// Use discretionary for non-urgent work
let config = URLSessionConfiguration.background(withIdentifier: "com.app.upload")
config.isDiscretionary = true  // Wait for good network/power conditions

// Require power for heavy work
let request = BGProcessingTaskRequest(identifier: "com.app.process")
request.requiresExternalPower = true

Respect User Settings

func scheduleRefreshIfAllowed() {
    // Check if user has Low Power Mode
    if ProcessInfo.processInfo.isLowPowerModeEnabled {
        // Reduce frequency or skip
        return
    }

    // Check background refresh status
    switch UIApplication.shared.backgroundRefreshStatus {
    case .available:
        scheduleAppRefresh()
    case .denied, .restricted:
        // Inform user if needed
        break
    @unknown default:
        break
    }
}

Handle Expiration

Always handle task expiration:

func handleTask(_ task: BGTask) {
    let operation = Task {
        // Long running work
    }

    // CRITICAL: Always set expiration handler
    task.expirationHandler = {
        operation.cancel()
        // Clean up
        // Save progress
    }
}

Progress Persistence

Save progress so you can resume:

func performIncrementalSync(task: BGTask) async {
    // Load progress
    let lastSyncDate = UserDefaults.standard.object(forKey: "lastSyncDate") as? Date ?? .distantPast

    do {
        // Sync from last position
        let newDate = try await syncSince(lastSyncDate)

        // Save progress
        UserDefaults.standard.set(newDate, forKey: "lastSyncDate")

        task.setTaskCompleted(success: true)
    } catch {
        task.setTaskCompleted(success: false)
    }
}

Debugging

Check Scheduled Tasks

BGTaskScheduler.shared.getPendingTaskRequests { requests in
    for request in requests {
        print("Pending: \(request.identifier)")
        print("Earliest: \(request.earliestBeginDate ?? Date())")
    }
}

Cancel Tasks

// Cancel specific
BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: "com.app.refresh")

// Cancel all
BGTaskScheduler.shared.cancelAllTaskRequests()

Console Logs

# View background task logs
log stream --predicate 'subsystem == "com.apple.BackgroundTasks"' --level debug

Reference: Ci Cd

CI/CD

Xcode Cloud, fastlane, and automated testing and deployment.

Xcode Cloud

Setup

1. Enable in Xcode: Product > Xcode Cloud > Create Workflow
2. Configure in App Store Connect

Basic Workflow

# Configured in Xcode Cloud UI
Workflow: Build and Test
Start Conditions:
  - Push to main
  - Pull Request to main

Actions:
  - Build
  - Test (iOS Simulator)

Post-Actions:
  - Notify (Slack)

Custom Build Scripts

.ci_scripts/ci_post_clone.sh:

#!/bin/bash
set -e

# Install dependencies
brew install swiftlint

# Generate files
cd $CI_PRIMARY_REPOSITORY_PATH
./scripts/generate-assets.sh

.ci_scripts/ci_pre_xcodebuild.sh:

#!/bin/bash
set -e

# Run SwiftLint
swiftlint lint --strict --reporter json > swiftlint-report.json || true

# Check for errors
if grep -q '"severity": "error"' swiftlint-report.json; then
    echo "SwiftLint errors found"
    exit 1
fi

Environment Variables

Set in Xcode Cloud:

• API_BASE_URL
• SENTRY_DSN
• Secrets (automatically masked)

Access in build:

let apiURL = Bundle.main.infoDictionary?["API_BASE_URL"] as? String

Fastlane

Installation

# Install
brew install fastlane

# Or via bundler
bundle init
echo 'gem "fastlane"' >> Gemfile
bundle install

Fastfile

fastlane/Fastfile:

default_platform(:ios)

platform :ios do
  desc "Run tests"
  lane :test do
    run_tests(
      scheme: "MyApp",
      device: "iPhone 16",
      code_coverage: true
    )
  end

  desc "Build and upload to TestFlight"
  lane :beta do
    # Increment build number
    increment_build_number(
      build_number: latest_testflight_build_number + 1
    )

    # Build
    build_app(
      scheme: "MyApp",
      export_method: "app-store"
    )

    # Upload
    upload_to_testflight(
      skip_waiting_for_build_processing: true
    )

    # Notify
    slack(
      message: "New build uploaded to TestFlight!",
      slack_url: ENV["SLACK_URL"]
    )
  end

  desc "Deploy to App Store"
  lane :release do
    # Ensure clean git
    ensure_git_status_clean

    # Build
    build_app(
      scheme: "MyApp",
      export_method: "app-store"
    )

    # Upload
    upload_to_app_store(
      submit_for_review: true,
      automatic_release: true,
      force: true,
      precheck_include_in_app_purchases: false
    )

    # Tag
    add_git_tag(
      tag: "v#{get_version_number}"
    )
    push_git_tags
  end

  desc "Sync certificates and profiles"
  lane :sync_signing do
    match(
      type: "appstore",
      readonly: true
    )
    match(
      type: "development",
      readonly: true
    )
  end

  desc "Take screenshots"
  lane :screenshots do
    capture_screenshots(
      scheme: "MyAppUITests"
    )
    frame_screenshots(
      white: true
    )
  end
end

Match (Code Signing)

fastlane/Matchfile:

git_url("https://github.com/yourcompany/certificates")
storage_mode("git")
type("appstore")
app_identifier(["com.yourcompany.app"])
username("[email protected]")

Setup:

# Initialize
fastlane match init

# Generate certificates
fastlane match appstore
fastlane match development

Appfile

fastlane/Appfile:

app_identifier("com.yourcompany.app")
apple_id("[email protected]")
itc_team_id("123456")
team_id("ABCDEF1234")

GitHub Actions

Basic Workflow

.github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: macos-14

    steps:
    - uses: actions/checkout@v4

    - name: Select Xcode
      run: sudo xcode-select -s /Applications/Xcode_15.4.app

    - name: Cache SPM
      uses: actions/cache@v3
      with:
        path: |
          ~/Library/Caches/org.swift.swiftpm
          .build
        key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}

    - name: Build
      run: |
        xcodebuild build \
          -project MyApp.xcodeproj \
          -scheme MyApp \
          -destination 'platform=iOS Simulator,name=iPhone 16' \
          CODE_SIGNING_REQUIRED=NO

    - name: Test
      run: |
        xcodebuild test \
          -project MyApp.xcodeproj \
          -scheme MyApp \
          -destination 'platform=iOS Simulator,name=iPhone 16' \
          -resultBundlePath TestResults.xcresult \
          CODE_SIGNING_REQUIRED=NO

    - name: Upload Results
      if: always()
      uses: actions/upload-artifact@v3
      with:
        name: test-results
        path: TestResults.xcresult

  deploy:
    needs: test
    runs-on: macos-14
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v4

    - name: Install Fastlane
      run: brew install fastlane

    - name: Deploy to TestFlight
      env:
        APP_STORE_CONNECT_API_KEY_KEY_ID: ${{ secrets.ASC_KEY_ID }}
        APP_STORE_CONNECT_API_KEY_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
        APP_STORE_CONNECT_API_KEY_KEY: ${{ secrets.ASC_KEY }}
        MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
        MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_AUTH }}
      run: fastlane beta

Code Signing in CI

- name: Import Certificate
  env:
    CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
    CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
    KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
  run: |
    # Create keychain
    security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
    security default-keychain -s build.keychain
    security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain

    # Import certificate
    echo "$CERTIFICATE_BASE64" | base64 --decode > certificate.p12
    security import certificate.p12 \
      -k build.keychain \
      -P "$CERTIFICATE_PASSWORD" \
      -T /usr/bin/codesign

    # Allow codesign access
    security set-key-partition-list \
      -S apple-tool:,apple:,codesign: \
      -s -k "$KEYCHAIN_PASSWORD" build.keychain

- name: Install Provisioning Profile
  env:
    PROVISIONING_PROFILE_BASE64: ${{ secrets.PROVISIONING_PROFILE_BASE64 }}
  run: |
    mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
    echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode > profile.mobileprovision
    cp profile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/

Version Management

Automatic Versioning

# In Fastfile
lane :bump_version do |options|
  # Get version from tag or parameter
  version = options[:version] || git_tag_last_match(pattern: "v*").gsub("v", "")

  increment_version_number(
    version_number: version
  )

  increment_build_number(
    build_number: number_of_commits
  )
end

Semantic Versioning Script

#!/bin/bash
# scripts/bump-version.sh

TYPE=$1  # major, minor, patch
CURRENT=$(agvtool what-marketing-version -terse1)

IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"

case $TYPE in
  major)
    MAJOR=$((MAJOR + 1))
    MINOR=0
    PATCH=0
    ;;
  minor)
    MINOR=$((MINOR + 1))
    PATCH=0
    ;;
  patch)
    PATCH=$((PATCH + 1))
    ;;
esac

NEW_VERSION="$MAJOR.$MINOR.$PATCH"
agvtool new-marketing-version $NEW_VERSION
echo "Version bumped to $NEW_VERSION"

Test Reporting

JUnit Format

xcodebuild test \
    -project MyApp.xcodeproj \
    -scheme MyApp \
    -destination 'platform=iOS Simulator,name=iPhone 16' \
    -resultBundlePath TestResults.xcresult

# Convert to JUnit
xcrun xcresulttool get --format json --path TestResults.xcresult > results.json
# Use xcresult-to-junit or similar tool

Code Coverage

# Generate coverage
xcodebuild test \
    -enableCodeCoverage YES \
    -resultBundlePath TestResults.xcresult

# Export coverage report
xcrun xccov view --report --json TestResults.xcresult > coverage.json

Slack Notifications

# In Fastfile
after_all do |lane|
  slack(
    message: "Successfully deployed to TestFlight",
    success: true,
    default_payloads: [:git_branch, :git_author]
  )
end

error do |lane, exception|
  slack(
    message: "Build failed: #{exception.message}",
    success: false
  )
end

App Store Connect API

Key Setup

1. App Store Connect > Users and Access > Keys
2. Generate Key with App Manager role
3. Download .p8 file

Fastlane Configuration

fastlane/Appfile:

# Use API Key instead of password
app_store_connect_api_key(
  key_id: ENV["ASC_KEY_ID"],
  issuer_id: ENV["ASC_ISSUER_ID"],
  key_filepath: "./AuthKey.p8",
  in_house: false
)

Upload with altool

xcrun altool --upload-app \
    --type ios \
    --file build/MyApp.ipa \
    --apiKey $KEY_ID \
    --apiIssuer $ISSUER_ID

Best Practices

Secrets Management

• Never commit secrets to git
• Use environment variables or secret managers
• Rotate keys regularly
• Use match for certificate management

Build Caching

# Cache derived data
- uses: actions/cache@v3
  with:
    path: |
      ~/Library/Developer/Xcode/DerivedData
      ~/Library/Caches/org.swift.swiftpm
    key: ${{ runner.os }}-build-${{ hashFiles('**/*.swift') }}