Splitting an iOS release into six fastlane lanes — Filmtone's archive / screenshots / metadata / beta / release / submit_review design

Splitting fastlane into six lanes by responsibility

Filmtone iOS's fastlane/Fastfile is split into six lanes. Each lane owns a single stage of the pipeline — build the IPA, stage review assets, submit for review — with no spillover side effects (no implicit re-archive, no surprise screenshot regeneration, no quiet metadata overwrite). The same Fastfile drives both CI and a laptop without surprises.

• archive — builds the IPA at build/fastlane/Filmtone.ipa with Xcode automatic signing
• screenshots — runs the UI test rail on iPhone 17 Pro Max (hard-coded UDID), then stages output for ja and en-US
• metadata — uploads localized metadata, review info, and release notes to App Store Connect. Never touches binary or screenshots
• beta — uploads an existing IPA to TestFlight. Always requires explicit IPA_PATH
• release — uploads IPA + metadata + screenshots to ASC. SUBMIT_FOR_REVIEW=1 submits for review; AUTOMATIC_RELEASE=1 auto-releases on approval
• submit_review — re-submits an already-uploaded build for review without touching binary or screenshots, given APP_VERSION and BUILD_NUMBER

Fail-fast when no IPA is provided

beta, release, and submit_review all funnel through explicit_ipa_path!(options, lane:). Skip ipa: and the lane bails immediately with UI.user_error!. Without this, CI quietly reuses a stale archive, or running release locally with no archive triggers a surprise 30-minute build.

def explicit_ipa_path!(options, lane:)
  explicit_path = options[:ipa] || options["ipa"]
  UI.user_error!(
    "Pass ipa:... to `fastlane ios #{lane}`. Implicit archive fallback is disabled."
  ) if explicit_path.nil?

  ipa_path = File.expand_path(explicit_path, APP_ROOT)
  UI.user_error!("IPA not found at #{ipa_path}") unless File.exist?(ipa_path)
  ipa_path
end

Trap 1 — gym 2.233 passes auth args twice

Fastlane 2.233.0's gym (build_app) forwards both export_xcargs and xcargs to xcodebuild -exportArchive during the export step. If the Fastfile sets the same App Store Connect auth args (-authenticationKeyIssuerID / -authenticationKeyID / -authenticationKeyPath) in both xcargs and export_xcargs, xcodebuild -exportArchive receives them twice and dies with Exit status: 64. The Xcode archive itself succeeds, only IPA export fails.

Minimum-viable fix: keep auth args in xcargs and don't set export_xcargs. Fastlane internally reuses xcargs during export, so the args reach xcodebuild -exportArchive once.

lane :archive do
  xcargs_parts = ["-allowProvisioningUpdates"]
  if asc_api_key_configured?
    key_file_path = temp_key_path || File.expand_path(env!("ASC_KEY_PATH"), APP_ROOT)
    xcargs_parts.concat([
      "-authenticationKeyIssuerID", env!("ASC_ISSUER_ID"),
      "-authenticationKeyID", env!("ASC_KEY_ID"),
      "-authenticationKeyPath", key_file_path,
    ])
  end
  xcargs = xcargs_parts.map(&:shellescape).join(" ")

  build_app(
    workspace: IOS_WORKSPACE,
    scheme: "App",
    clean: true,
    export_method: "app-store",
    output_directory: BUILD_OUTPUT_DIR,
    output_name: "Filmtone",
    build_path: BUILD_OUTPUT_DIR,
    xcargs: xcargs,
    export_options: {
      method: "app-store",
      signingStyle: "automatic",
      teamID: DEVELOPMENT_TEAM_ID,
    }
  )
end

Trap 2 — release_notes silently dropped means `whatsNew` is missing

Even when fastlane/metadata/{ja,en-US}/release_notes.txt exists on disk, calling upload_to_app_store without explicitly passing release_notes: makes the ASC API treat whatsNew as unset. Binary upload, screenshot upload, precheck, and build selection all succeed — then submit_for_review: true fails with:

appStoreVersions ... is not in valid state.
The provided entity is missing a required attribute - You must provide a value for the attribute 'whatsNew' with this request

Fix: pass release_notes: explicitly. The same payload is needed in metadata, release, and submit_review, so factor it into a helper and reference it from each lane. TestFlight (beta lane) wants localized_build_info shaped as { locale => { whats_new: text } }, so a second helper re-shapes the same source.

def localized_release_note_texts
  {
    "ja" => read_text_if_present(File.join(METADATA_TEMPLATE_PATH, "ja", "release_notes.txt")),
    "en-US" => read_text_if_present(File.join(METADATA_TEMPLATE_PATH, "en-US", "release_notes.txt")),
  }.compact
end

def localized_build_release_notes
  localized_release_note_texts.each_with_object({}) do |(locale, notes), memo|
    memo[locale] = { whats_new: notes }
  end
end

submit_review — re-submit an existing build without touching the binary

When release failed at submit_for_review due to missing whatsNew, the binary was already at ASC. No need to re-archive — only metadata and the review submission need to land. That's exactly what submit_review does. It pulls APP_VERSION and BUILD_NUMBER from env or lane options, then runs upload_to_app_store with skip_binary_upload: true, skip_screenshots: true, skip_metadata: false.

lane :submit_review do |options|
  app_version = normalized_env("APP_VERSION") || options[:app_version]
  build_number = normalized_env("BUILD_NUMBER") || options[:build_number]

  UI.user_error!("Set APP_VERSION or pass app_version:") unless app_version
  UI.user_error!("Set BUILD_NUMBER or pass build_number:") unless build_number

  upload_to_app_store(
    api_key: load_asc_api_key!,
    app_identifier: APP_IDENTIFIER,
    app_version: app_version,
    build_number: build_number,
    platform: "ios",
    metadata_path: stage_metadata!,
    skip_binary_upload: true,
    skip_screenshots: true,
    skip_metadata: false,
    submit_for_review: true,
    automatic_release: truthy_env?("AUTOMATIC_RELEASE"),
    release_notes: localized_release_note_texts,
    # ...
  )
end

Closing the screenshot-asymmetry door upstream

Because release will overwrite ASC screenshots, mismatched per-locale counts or filenames corrupt the App Store screenshot panel. The Fastfile runs validate_release_screenshots! before any upload: both ja and en-US must have 1–10 screenshots, with identical filename order across locales. Anything else fails fast via UI.user_error!.

def validate_release_screenshots!
  screenshot_paths = staged_release_screenshot_paths
  missing_locales = screenshot_paths.select { |_, paths| paths.empty? }.keys
  unless missing_locales.empty?
    UI.user_error!("Missing staged screenshots for locales: #{missing_locales.join(', ')}")
  end

  counts = screenshot_paths.transform_values(&:count)
  unless counts.values.all? { |count| count.between?(1, 10) }
    UI.user_error!("Each locale must have between 1 and 10 screenshots.")
  end
  unless counts.values.uniq.one?
    UI.user_error!("Screenshot counts differ by locale.")
  end

  expected_basenames = nil
  screenshot_paths.each do |locale, paths|
    basenames = paths.map { |path| File.basename(path) }
    expected_basenames ||= basenames
    next if basenames == expected_basenames
    UI.user_error!("Screenshot filenames must match across locales.")
  end
end

Final v1.2 submission flow

# 1. archive once
bun run release:archive   # → build/fastlane/Filmtone.ipa

# 2. upload metadata and binary (does not submit for review yet)
IPA_PATH=build/fastlane/Filmtone.ipa \
  bun run release:appstore

# 3. when whatsNew rejects review submission, re-send metadata only and submit
set -a; . ./.env.local; set +a
APP_VERSION=1.2 BUILD_NUMBER=1 AUTOMATIC_RELEASE=1 \
  ./scripts/bundle.sh exec fastlane ios submit_review