Skip to content
RunnerHub

Quick Start - iOS with Fastlane

This guide walks you through setting up a RunnerHub pipeline with Fastlane, the popular automation tool for iOS development. Fastlane simplifies complex build, test, and deployment workflows.

Prerequisites

Section titled “Prerequisites”

Step 1: Create the Pipeline YAML

Section titled “Step 1: Create the Pipeline YAML”

Create .runnerhub/runnerhub.yml in your repository root:

name: iOS Build
platform: ios


environment:
  xcode: "16.4"


triggers:
  - push
  - pull_request


steps:
  - name: Install gems
    run: bundle install


  - name: Install pods
    run: pod install


  - name: Build app
    run: fastlane build

This pipeline:

  1. Installs Ruby gems (including Fastlane) from your Gemfile.lock
  2. Installs CocoaPods dependencies
  3. Runs your build Fastlane lane

Step 2: Configure Fastlane Lanes

Section titled “Step 2: Configure Fastlane Lanes”

Make sure your fastlane/Fastfile includes the lane you referenced in the pipeline. For example:

default_platform(:ios)


platform :ios do
  desc "Build the iOS app"
  lane :build do
    build_app(
      workspace: "MyApp.xcworkspace",
      scheme: "MyApp",
      configuration: "Debug",
      sdk: "iphonesimulator",
      destination: "generic/platform=iOS Simulator",
      skip_package_ipa: true,
      skip_package_pkg: true
    )
  end


  desc "Run tests"
  lane :test do
    run_tests(
      workspace: "MyApp.xcworkspace",
      scheme: "MyApp",
      destination: "generic/platform=iOS Simulator"
    )
  end
end

Step 3: Add Signing Credentials as Environment Variables

Section titled “Step 3: Add Signing Credentials as Environment Variables”

If your Fastlane lanes need secrets (API keys, certificates, etc.), add them to your app in the RunnerHub dashboard:

  1. Go to your app > Environment
  2. Add environment variables like APPLE_ID, APP_STORE_CONNECT_API_KEY, etc.
  3. Reference them in your YAML using $VARIABLE_NAME:
steps:
  - name: Build app
    run: fastlane build
    env:
      APPLE_ID: $APPLE_ID
      APPLE_ID_PASSWORD: $APPLE_ID_PASSWORD

Complete Example: TestFlight Deploy

Section titled “Complete Example: TestFlight Deploy”

Here’s a complete pipeline that builds and deploys to TestFlight:

name: TestFlight Deploy
platform: ios


environment:
  xcode: "16.4"


triggers:
  - push


steps:
  - name: Install gems
    run: bundle install


  - name: Install pods
    run: pod install


  - name: Build and deploy
    run: fastlane beta
    env:
      APP_STORE_CONNECT_API_KEY: $APP_STORE_CONNECT_API_KEY
      APP_STORE_CONNECT_ISSUER_ID: $APP_STORE_CONNECT_ISSUER_ID


artifacts:
  - build/**/*.ipa

And your fastlane/Fastfile:

lane :beta do
  build_app(
    workspace: "MyApp.xcworkspace",
    scheme: "MyApp",
    configuration: "Release",
    export_method: "app-store"
  )


  upload_to_testflight(
    api_key_path: "path/to/AuthKey.p8",
    skip_waiting_for_build_processing: true
  )
end

Best Practices

Section titled “Best Practices”

Use bundle exec for consistency:

- name: Run tests
  run: bundle exec fastlane test

Pin gem versions in your Gemfile:

gem 'fastlane', '~> 2.218.0'

Organize lanes logically:

lane :ci do
  setup_ci if is_ci
  build
  test
end

Caching

Section titled “Caching”

RunnerHub automatically caches:

  • Ruby gems (from your Gemfile.lock)
  • CocoaPods dependencies
  • Fastlane plugins

Your builds will be fast after the first run!

Common Fastlane Lanes

Section titled “Common Fastlane Lanes”

Test Lane:

lane :test do
  run_tests(
    workspace: "MyApp.xcworkspace",
    scheme: "MyApp"
  )
end

Release Lane:

lane :release do
  build_app(
    workspace: "MyApp.xcworkspace",
    scheme: "MyApp",
    configuration: "Release",
    export_method: "app-store"
  )


  upload_to_app_store(
    api_key_path: "path/to/AuthKey.p8"
  )
end

What’s Next?

Section titled “What’s Next?”

Code Signing

Set up code signing for TestFlight and App Store distribution in the signing guide.