Fastlane CI skill for Claude Code

Done well means: one command per destination (bundle exec fastlane ios beta, bundle exec fastlane android internal) that runs identically on a laptop and in CI, signs with read-only certificates from match, authenticates with API keys instead of an Apple ID, numbers builds automatically, and never ships to 100% of production in one step.

Store policy, review, and rollout judgement live in app-store-release; this skill is the automation layer.

Before changing anything

• Run bundle exec fastlane lanes and read fastlane/Fastfile, Appfile, Matchfile, Pluginfile, Gemfile.lock. Note the fastlane version and plugins.
• Run the bundled checker for known hazards: python3 scripts/check_fastlane.py <project-root> (exit 1 means secrets or destructive actions are committed; fix those first).
• Identify current signing: Xcode automatic signing, manual profiles, or match (which storage: git, google_cloud, s3, gitlab_secure_files).
• List the CI secrets that exist. Never print them in logs while investigating.

Workflow

- [ ] 1. Gemfile with fastlane pinned; Gemfile.lock committed; always `bundle exec`
- [ ] 2. Appfile with app_identifier / package_name (and team_id if several teams)
- [ ] 3. App Store Connect API key (.p8) stored as a base64 CI secret
- [ ] 4. match repo/bucket initialized once by a human; CI uses readonly
- [ ] 5. Lanes: ios beta, ios release, android internal, android promote
- [ ] 6. Build numbers derived from the store (or CI run number), never hand-edited
- [ ] 7. CI workflow with Ruby + bundler cache, Xcode pinned, secrets as env vars
- [ ] 8. Dry run on a branch, then protect release lanes behind tags or manual approval

Setup

# Gemfile
source "https://rubygems.org"
gem "fastlane", "~> 2.228"      # pin a minor range; bump deliberately
plugins_path = File.join(File.dirname(__FILE__), "fastlane", "Pluginfile")
eval_gemfile(plugins_path) if File.exist?(plugins_path)

# fastlane/Appfile
app_identifier(ENV.fetch("APP_IDENTIFIER", "com.acme.app"))
team_id(ENV["APPLE_TEAM_ID"])                 # only if the key/account spans teams
package_name("com.acme.app")

For Play, pass the service-account JSON from a secret as json_key_data: ENV["PLAY_JSON_KEY"] on each Play action (or write it to a temp file and set json_key:); never commit the file.

Signing with match

Decision	Default
Storage	Private git repo with a deploy key, or google_cloud / s3 bucket if git access is awkward
Types	development for local, appstore for TestFlight and App Store, adhoc only for device farms
Who writes	One human on a trusted machine runs fastlane match appstore once per new app or cert expiry
CI	match(type: "appstore", readonly: true) — never creates or revokes anything
Encryption	MATCH_PASSWORD secret; rotate if anyone with access leaves

• fastlane match nuke revokes all certificates of a type for the whole team and breaks every other machine. Run it only manually and only after the user explicitly confirms.
• Apple allows few distribution certificates per account; match shares one across the team instead of each developer creating their own.
• New bundle IDs, App Groups, or capabilities: regenerate profiles with a writable run (match appstore --force_for_new_devices or --force) from a trusted machine, then CI picks them up read-only.
• Set setup_ci in before_all so CI uses a temporary keychain. Without it, codesign on a CI macOS runner waits forever for a keychain password prompt.

iOS lanes

default_platform(:ios)

platform :ios do
  before_all do
    setup_ci if is_ci
  end

  private_lane :asc_key do
    app_store_connect_api_key(
      key_id: ENV.fetch("ASC_KEY_ID"),
      issuer_id: ENV.fetch("ASC_ISSUER_ID"),
      key_content: ENV.fetch("ASC_KEY_P8_BASE64"),
      is_key_content_base64: true,
      in_house: false
    )
  end

  desc "Build and upload to TestFlight"
  lane :beta do
    api_key = asc_key
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      xcodeproj: "App.xcodeproj",
      build_number: latest_testflight_build_number(api_key: api_key, initial_build_number: 0) + 1
    )
    build_app(scheme: "App", configuration: "Release", export_method: "app-store",
              clean: true, output_directory: "build")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true,
                         changelog: ENV.fetch("CHANGELOG", "Internal build"))
  end
end

• latest_testflight_build_number queries the store, so two CI runs can race. Serialize release lanes (concurrency group) or use the CI run number as the build number.
• skip_waiting_for_build_processing: true saves 10-30+ minutes of macOS time. Leave it false only when the same lane distributes to external testers.
• Pin Xcode on the runner (xcodes action or sudo xcode-select -s). Apple raises the minimum SDK for uploads each spring; a runner image update can silently change Xcode.

Android lanes

platform :android do
  desc "Build AAB and upload to internal testing"
  lane :internal do
    code = (google_play_track_version_codes(track: "internal").max || 0) + 1
    gradle(
      task: "bundle", build_type: "Release",
      properties: {
        "versionCode" => code,                                   # read in build.gradle.kts
        "android.injected.signing.store.file" => ENV.fetch("UPLOAD_KEYSTORE_PATH"),
        "android.injected.signing.store.password" => ENV.fetch("UPLOAD_KEYSTORE_PASSWORD"),
        "android.injected.signing.key.alias" => ENV.fetch("UPLOAD_KEY_ALIAS"),
        "android.injected.signing.key.password" => ENV.fetch("UPLOAD_KEY_PASSWORD")
      }
    )
    upload_to_play_store(track: "internal", json_key_data: ENV.fetch("PLAY_JSON_KEY"),
                         aab: lane_context[SharedValues::GRADLE_AAB_OUTPUT_PATH],
                         skip_upload_metadata: true, skip_upload_images: true,
                         skip_upload_screenshots: true)
  end

  desc "Promote internal to production at 10%"
  lane :promote do
    upload_to_play_store(track: "internal", track_promote_to: "production",
                         json_key_data: ENV.fetch("PLAY_JSON_KEY"),
                         skip_upload_aab: true, skip_upload_apk: true,
                         rollout: "0.1", skip_upload_changelogs: false)
  end
end

• The keystore here is the upload key; Play App Signing holds the app signing key. Decode the keystore from a base64 secret into a temp file in a CI step.
• Make versionCode a Gradle property with a local default so local builds still work.
• Validate the service account once: bundle exec fastlane run validate_play_store_json_key json_key:path.json.
• The very first upload of a new app must be done manually in Play Console; the API cannot create the app listing.
• Draft apps (never published) accept only release_status: "draft" uploads.

CI workflow (GitHub Actions)

name: ios-beta
on:
  workflow_dispatch:
  push:
    tags: ["v*"]
concurrency: { group: ios-release, cancel-in-progress: false }
jobs:
  beta:
    runs-on: macos-15
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with: { bundler-cache: true }
      - run: sudo xcode-select -s /Applications/Xcode_26.0.app   # pin; check runner image
      - run: bundle exec fastlane ios beta
        env:
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_KEY_P8_BASE64: ${{ secrets.ASC_KEY_P8_BASE64 }}
          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
          MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_BASIC_AUTHORIZATION }}
          FASTLANE_SKIP_UPDATE_CHECK: "1"
          FASTLANE_HIDE_CHANGELOG: "1"

Check which Xcode versions the runner image actually ships before pinning a path. Cache SwiftPM (~/Library/Caches/org.swift.swiftpm, SourcePackages) and Gradle (actions/setup-java with cache: gradle) to cut build time. Android lanes run on ubuntu-latest; keep macOS minutes for iOS only.

Failure triage

Symptom	Likely cause	Fix
Hangs at codesign / errSecInternalComponent	Login keychain on CI	setup_ci in before_all
“No profiles for ‘com.x’ were found”	Profile missing the bundle ID, capability, or extension target	Writable match run from trusted machine; include every target’s bundle ID in app_identifier array
2FA / session expired	Apple ID auth	Switch every action to api_key:
“Redundant binary upload” / build number exists	Reused build number	Derive from latest_testflight_build_number + 1
Play: “Version code has already been used”	Same	Derive from google_play_track_version_codes across all tracks
Play: 403 / “caller does not have permission”	Service account not invited in Play Console or missing release permission	Invite account in Users and permissions for this app
Works locally, fails in CI	Different Xcode, Ruby, or fastlane version	Pin Xcode, commit Gemfile.lock, bundle exec everywhere

Gotchas

• Running fastlane without bundle exec uses whatever global version is installed.
• App extensions (widgets, notification service) need their own bundle IDs in match and their own profiles; pass an array to app_identifier.
• increment_build_number edits the project; commit it back only if your process wants that, otherwise keep build numbers ephemeral in CI.
• Secrets passed via sh("... #{ENV['X']}") appear in logs; pass via env instead.
• Fastlane’s Apple ID password env vars and app-specific passwords are legacy for uploads; App Store Connect API keys cover TestFlight, metadata, and match.

Verification

1. python3 scripts/check_fastlane.py . reports 0 errors; review each warning.
2. bundle exec fastlane lanes lists the expected lanes with descriptions.
3. Run the beta lane from CI on a branch; confirm the build appears in TestFlight and Play internal testing with the expected build number and version code.
4. Re-run the same workflow: it must succeed with the next build number, proving numbering and read-only signing are stable.
5. Confirm production lanes require a tag or manual approval and use a staged rollout.