Monorepo Setup

Monorepos house multiple projects in a single repository. This recipe demonstrates how to run build steps in specific subdirectories using the working_directory parameter.

Complete YAML

name: Monorepo iOS Build
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Install pods
    run: pod install
    working_directory: apps/ios

  - name: Build
    run: fastlane build
    working_directory: apps/ios

Multi-Project Monorepo

For repositories with multiple iOS apps:

name: Build Multiple Apps
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Install dependencies (App A)
    run: pod install
    working_directory: apps/app-a

  - name: Build App A
    run: fastlane build
    working_directory: apps/app-a

  - name: Install dependencies (App B)
    run: pod install
    working_directory: apps/app-b

  - name: Build App B
    run: fastlane build
    working_directory: apps/app-b

Monorepo with Shared Dependencies

name: Monorepo with Shared Code
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Install workspace gems
    run: bundle install

  - name: Install pod dependencies
    run: pod install
    working_directory: apps/mobile

  - name: Run tests
    run: fastlane test
    working_directory: apps/mobile

  - name: Build
    run: fastlane build
    working_directory: apps/mobile

Key Points

Tip

The working_directory parameter changes where the command executes. All paths in that step are relative to the specified directory.

• Root-level Operations: Commands without working_directory run from the repository root
• Subdirectory Operations: Commands with working_directory run in that subdirectory
• Relative Paths: Paths in steps are relative to their working_directory (if specified) or the repo root
• Shared Dependencies: Install workspace-level dependencies (e.g., bundle install) at the root, then app-specific dependencies in subdirectories

Repository Structure Examples

Flat Monorepo

my-monorepo/
├── Gemfile
├── apps/
│   ├── app-a/
│   │   ├── Podfile
│   │   ├── fastlane/
│   │   └── MyAppA.xcworkspace/
│   └── app-b/
│       ├── Podfile
│       ├── fastlane/
│       └── MyAppB.xcworkspace/
└── .runnerhub/
    └── runnerhub.yml

Nested Monorepo

my-project/
├── mobile/
│   ├── ios/
│   │   ├── Podfile
│   │   └── App.xcworkspace/
│   └── android/
│       └── build.gradle
├── backend/
│   └── package.json
└── .runnerhub/
    └── runnerhub.yml

Conditional Builds by Directory

You can use shell conditions to build only changed projects:

name: Conditional Monorepo Build
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build if iOS app changed
    run: |
      if git diff HEAD~1 HEAD --name-only | grep -q "apps/ios/"; then
        pod install && fastlane build
      else
        echo "No iOS changes, skipping build"
      fi
    working_directory: apps/ios

Caution

Ensure each subdirectory has its own Podfile, Gemfile, or dependency manifest. RunnerHub runs all steps sequentially, so build time increases with the number of projects.

Monorepo vs Shared Repository

These are two different approaches to multi-project builds:

Approach	Use Case	How It Works
Monorepo (this page)	Multiple projects in subdirectories	One app, one pipeline, working_directory per step
Shared Repository	White-label / multi-brand apps	Multiple apps connected to the same repo, each with its own pipeline YAML

For white-label apps, see Custom Pipeline Path and Shared Repositories.