Quick Start - Swift Packages

This guide walks you through setting up a RunnerHub pipeline for Swift Package Manager (SPM) projects. Build, test, and distribute your Swift packages with automated dependency caching.

Prerequisites

Note

Before you start, make sure you have:

• A Swift package with Package.swift in the repository root
• Xcode or Swift Command Line Tools installed
• A RunnerHub account at app.runnerhub.net
• Your Swift package repository connected via GitHub, GitLab, or Bitbucket

Step 1: Create the Pipeline

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

name: Swift Package Build
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Resolve dependencies
    run: swift package resolve

  - name: Build
    run: swift build

  - name: Run tests
    run: swift test

This pipeline builds your Swift package and runs all tests.

Step 2: Customize for Your Package

The basic pipeline works for most Swift packages. You can customize it:

• Add more tests: swift test -v for verbose output
• Build specific targets: swift build -c release
• Filter tests: swift test --filter YourPackageTests.YourTestClass

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 your Swift package build run in the dashboard

Complete Example

Here’s a more comprehensive pipeline with multiple test steps:

name: Swift Package Build & Test
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Resolve dependencies
    run: swift package resolve

  - name: Build (Debug)
    run: swift build

  - name: Build (Release)
    run: swift build -c release

  - name: Run tests
    run: swift test -v

  - name: Run performance tests
    run: swift test --filter YourPackageTests.PerformanceTests

Release Build

For distribution, build with the Release configuration:

name: Swift Package Release
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build Release
    run: swift build -c release

Multiple Platforms

Build for multiple platforms (iOS, macOS, etc.):

name: Swift Package Multi-Platform
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Resolve dependencies
    run: swift package resolve

  - name: Build for macOS
    run: swift build -c debug

  - name: Test on macOS
    run: swift test

  - name: Build for iOS
    run: |
      swift build \
      -c debug \
      --destination generic/platform=iOS

DocC Documentation

Build documentation with DocC:

name: Swift Package with Docs
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Resolve dependencies
    run: swift package resolve

  - name: Build
    run: swift build

  - name: Run tests
    run: swift test

  - name: Build documentation
    run: swift package generate-documentation

artifacts:
  - .build/**

Caching

RunnerHub automatically caches:

• Swift package dependencies (.build/checkouts/)
• Build artifacts (.build/ directory)
• Resolved dependencies

Your builds will be fast after the first run!

Updating Dependencies

To update package dependencies:

- name: Update dependencies
  run: swift package update

Or update to specific versions:

- name: Update specific package
  run: swift package edit PackageName --revision <commit-hash>

Code Coverage

Generate code coverage reports:

name: Swift Package with Coverage
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Run tests with coverage
    run: swift test --enable-code-coverage

  - name: Generate coverage report
    run: |
      xcrun llvm-cov export \
      -format="lcov" \
      .build/debug/YourPackagePackageTests.xctest/Contents/MacOS/YourPackagePackageTests \
      -instr-profile=.build/debug/codecov/default.profdata > coverage.lcov

artifacts:
  - coverage.lcov

Environment Variables

Add configuration via environment variables:

steps:
  - name: Build
    run: swift build
    env:
      CONFIGURATION: release
      ENABLE_TESTS: true

Reference them in your Package.swift or build scripts.

Swift Version

Specify a Swift version (if needed):

- name: Check Swift version
  run: swift --version

- name: Build with specific tools
  run: swift build

Lint and Format

Add linting before building:

name: Swift Package Lint & Build
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Resolve dependencies
    run: swift package resolve

  - name: Format check
    run: swift run swiftformat --lint .

  - name: Build
    run: swift build

  - name: Run tests
    run: swift test

Monorepo Setup

If your Swift package is in a subdirectory:

name: Swift Package Monorepo
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Build
    run: swift build
    working_directory: packages/MyPackage

  - name: Test
    run: swift test
    working_directory: packages/MyPackage

Tips & Troubleshooting

Show verbose output:

- name: Build verbose
  run: swift build -v

List available targets:

- name: List targets
  run: swift package describe

Force rebuild:

- name: Clean and build
  run: |
    rm -rf .build
    swift build

Run specific test target:

- name: Run specific tests
  run: swift test --filter PackageNameTests

What’s Next?

iOS Native

Building an iOS app instead? See the iOS native guide.

iOS with Fastlane

Need automation? Check the Fastlane guide.

Pipeline Reference

Explore all YAML options in the pipeline reference.

Caching & Performance

Learn how RunnerHub caches dependencies in the caching guide.