Run Your First Pipeline

A pipeline is defined in .runnerhub/runnerhub.yml in your repository root. This file tells RunnerHub what to build and how to build it.

Create Your Pipeline File

1. In your repository, create a directory named .runnerhub in the root
2. Inside that directory, create a file named runnerhub.yml
3. Add the following minimal pipeline:

name: My First Build
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build
    run: xcodebuild -scheme MyApp -sdk iphonesimulator build

Replace MyApp with your actual Xcode scheme name.

Understanding Your Pipeline

Let’s break down what each line does:

Field	Meaning
name	Display name for this pipeline (shown in the dashboard)
platform	Target platform: ios, macos, android, flutter, or react-native
triggers	When to run: push (every commit), pull_request, manual, or schedule. You can also filter by branch (see Triggers guide)
steps	List of commands to execute in order

Each step has:

• name — Description of what this step does
• run — Shell command to execute

Common Pipeline Examples

iOS App with Tests

name: iOS CI
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Install Dependencies
    run: pod install
  - name: Run Tests
    run: xcodebuild -scheme MyApp -sdk iphonesimulator test
  - name: Build for Simulator
    run: xcodebuild -scheme MyApp -sdk iphonesimulator build

macOS App

name: macOS Build
platform: macos

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build
    run: xcodebuild -scheme MyMacApp build
  - name: Create DMG
    run: |
      hdiutil create -volname "MyApp" \
        -srcfolder build/Release \
        -ov -format UDZO MyApp.dmg

With Environment Variables

name: Build with Config
platform: ios

environment:
  xcode: "16.4"
  variables:
    TEAM_ID: ABC123DEF456
    BUNDLE_ID: com.example.myapp

triggers:
  - push

steps:
  - name: Build
    run: |
      xcodebuild \
        -scheme MyApp \
        -sdk iphonesimulator \
        TEAM_ID=${TEAM_ID} \
        build

With Fastlane

name: Fastlane Build
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Install Fastlane
    run: gem install fastlane
  - name: Build and Sign
    run: fastlane build
    env:
      FASTLANE_USER: $APPLE_ID
      FASTLANE_PASSWORD: $APPLE_PASSWORD

Tip

Store secrets in the dashboard (App → Environment) and reference them as $KEY_NAME in your pipeline. They are masked in logs automatically.

Push and Trigger Your First Build

1. Commit and push your changes:

   git add .runnerhub/runnerhub.yml
   git commit -m "Add RunnerHub pipeline"
   git push origin main

2. Watch the magic happen:

   • RunnerHub receives a webhook from GitHub/GitLab/Bitbucket
   • A new build is queued
   • Your dedicated agent picks it up
   • Steps execute one by one

3. View the results:

   • Go to app.runnerhub.net
   • Click your app
   • View the latest build
   • Check logs for each step

What Happens During a Build

1. Job received and queued
   ↓
2. Dedicated Mac agent assigned
   ↓
3. Repository cloned to agent
   ↓
4. .runnerhub/runnerhub.yml parsed
   ↓
5. Environment variables set up
   ↓
6. Each step runs sequentially
   ↓
7. Logs streamed to dashboard in real-time
   ↓
8. Step succeeds or fails
   ↓
9. If all steps succeed: Build marked SUCCESS
   ↓
10. If any step fails: Build marked FAILED
    (Remaining steps skipped unless configured to continue)

Build Output and Logs

During and after your build, you can:

• View live logs — See step output as it executes
• Search logs — Find specific errors or warnings
• Download logs — Save the full log file for debugging
• View artifacts — If your pipeline creates build products
• Check timing — See how long each step took

Debugging a Failed Build

If your build fails:

1. Read the error message — The last few lines of a failing step usually contain the issue
2. Check your Xcode scheme — Is it spelled correctly? Does it exist?
3. Verify dependencies — If using CocoaPods, did pod install succeed?
4. Review build settings — Are SDK, team ID, or provisioning profile settings correct?
5. Test locally — Run the same command on your Mac to see if it’s a RunnerHub-specific issue
6. Check the FAQ — See Troubleshooting for common issues

Note

Every build runs on a fresh, isolated Mac mini. You can’t rely on state from previous builds. Make sure your pipeline includes all necessary setup steps (e.g., pod install before building).

Next Steps

Now that your first pipeline is running:

1. Learn more pipeline features — Variables, artifacts, conditionals (guide →)
2. Set up code signing — If you need to create signed IPAs or Mac apps (guide →)
3. Add scheduled builds — Run tests nightly or on a schedule (guide →)
4. Invite team members — Collaborate with colleagues (guide →)

Tip

The xcodebuild command can feel cryptic. If you’re using Fastlane, CocoaPods, or other build tools, check the Pipeline Cookbook for examples in your specific setup.