Quick Start - iOS Native

In this guide, you’ll set up a basic iOS build pipeline using Xcode’s native xcodebuild command. This is perfect for projects that don’t use Fastlane, or if you prefer direct Xcode control.

Prerequisites

Note

Before you start, make sure you have:

• An Xcode project (.xcodeproj or .xcworkspace)
• A RunnerHub account at app.runnerhub.net
• Your iOS repository connected via GitHub, GitLab, or Bitbucket
• CocoaPods installed (if your project uses pods)

Step 1: Create the Pipeline File

Create a new file at .runnerhub/runnerhub.yml in your repository root:

name: iOS Build
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Install pods
    run: pod install

  - name: Build app
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -sdk iphonesimulator \
      -configuration Debug \
      build

Tip

Replace MyApp.xcworkspace and MyApp with your actual workspace and scheme names. Use -sdk iphonesimulator for CI builds to avoid code signing requirements.

Step 2: Customize for Your Project

Update the YAML with your project details:

• workspace: Your .xcworkspace file name (or -project MyApp.xcodeproj if you don’t use CocoaPods)
• scheme: Your build scheme
• configuration: Debug or Release (default is Debug for CI)

For projects without CocoaPods, remove the pod install step.

Step 3: Push and Watch

1. Commit and push .runnerhub/runnerhub.yml to your repository
2. Go to app.runnerhub.net and navigate to your app
3. Watch the build run in real-time in the dashboard

Complete Example with Tests

Here’s a more complete pipeline that includes unit tests:

name: iOS Build & Test
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Install pods
    run: pod install

  - name: Run tests
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -destination 'platform=iOS Simulator,name=iPhone 15' \
      test

  - name: Build app
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -sdk iphonesimulator \
      build

Caching

RunnerHub automatically caches:

• CocoaPods (Pods/ directory)
• Xcode build artifacts (.build/, DerivedData/)

No extra configuration needed!

Tips & Troubleshooting

Using a .xcodeproj instead of .xcworkspace:

- name: Build app
  run: |
    xcodebuild \
    -project MyApp.xcodeproj \
    -scheme MyApp \
    -sdk iphonesimulator \
    build

Finding your scheme name:

xcodebuild -workspace MyApp.xcworkspace -list

Building for a specific simulator:

- name: Build app
  run: |
    xcodebuild \
    -workspace MyApp.xcworkspace \
    -scheme MyApp \
    -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
    build

What’s Next?

Code Signing

Ready to sign and distribute? See the code signing guide for distribution builds.

Fastlane Integration

Prefer Fastlane? Check out the Fastlane guide for lane automation.

Pipeline Configuration

Explore all pipeline options in the YAML reference.

Caching & Performance

Learn how RunnerHub caches dependencies automatically in caching docs.