IOS Starter Workflow: Automate Your Builds & Tests

Hey everyone! Let's dive into setting up an iOS starter workflow using GitHub Actions. This guide will help you automate your build and test processes, making your development life a whole lot easier. We'll be covering everything from the basics to more advanced configurations, so you can streamline your iOS project management. This workflow is designed to be a solid foundation for your iOS development, allowing you to ensure code quality and consistency with every push or pull request.

What is an iOS Starter Workflow?

An iOS starter workflow is essentially a set of automated tasks that are triggered by certain events in your Git repository. For example, when you push code to your main branch or open a pull request, the workflow kicks in. It automates the building and testing of your iOS app. This helps you catch errors early, ensures your code works as expected, and saves you time and effort by automating repetitive tasks. The workflow uses GitHub Actions to run on a Mac environment, leveraging Xcode to build and test your project. This includes checking out your code, determining the default scheme, building the app for testing, and then running the tests.

Think of it like having a diligent assistant who always checks your work and provides immediate feedback. The goal is to catch integration issues as early as possible in your development cycle. If the build fails or any tests fail, the workflow reports the issues. This allows you and your team to quickly identify and fix problems before they become bigger headaches. The setup we're outlining here focuses on building and testing the default scheme of an iOS project, but it can easily be modified and scaled to match the specific requirements of your project. It automatically picks an available iPhone simulator, builds the project, and runs tests using xcodebuild.

This workflow provides immediate feedback on the status of your code. If there are any build failures or test failures, you'll be notified right away. This helps you fix issues before they make their way into your main branch and potentially affect other team members or users. By using automation, you can be sure that your iOS app is consistently tested with every code change. This helps maintain a high level of code quality throughout the lifecycle of your project.

Setting Up Your Workflow

To get started, you'll need to create a new workflow file in your GitHub repository. This file, usually named ios-starter-workflow.yml, will live in the .github/workflows/ directory. The content of this file defines the steps that will be executed when the workflow is triggered. This YAML file contains the configuration for the workflow, specifying when it should run (on pushes to or pull requests against the main branch), what jobs should be executed, and the specific steps within those jobs.

The basic structure involves several key parts. First, you define when the workflow is triggered using the on: section. Next, you define jobs that specify what actions the workflow performs. Then, for each job, you specify what environment it runs on (e.g., macos-latest) and the individual steps. Each step within a job performs a specific task, such as checking out your code, setting up Xcode, building the app, or running tests. The workflow runs on macos-latest, which ensures that you have access to the latest versions of Xcode and related tools. This environment provides a clean, pre-configured environment to build and test your iOS project. You can customize it according to your specific needs, like selecting different Xcode versions or adding additional dependencies.

The core of the workflow involves running xcodebuild commands. The workflow will automatically detect the default scheme and select a suitable simulator for testing. This will reduce the manual setup and configuration necessary to get started. These commands build and test your project, mimicking what a developer would do. This automated process is designed to ensure your code is working correctly every time you commit it to your repository.

Understanding the YAML File

Let's break down the key parts of the YAML file to understand how it works. The first section specifies when the workflow is triggered.

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

This part of the file tells GitHub Actions to run this workflow whenever you push code to the main branch or create a pull request against the main branch. This ensures that every change you make gets automatically built and tested. This is a crucial step for maintaining the integrity of your main codebase. By running the workflow on every push and pull request, you can identify issues immediately and maintain code quality across the project.

Next, you define the job that will run. Here's the structure of the build job:

jobs:
  build:
    name: Build and Test default scheme using any available iPhone simulator
    runs-on: macos-latest

    steps:
      # ... (steps for checkout, build, and test) ...

In this example, the job is named build, and it runs on the latest macOS. The name is set to make it easier to identify in the GitHub Actions UI. The runs-on: macos-latest line defines the environment where the job runs. The steps section outlines the specific tasks to be performed.

The steps section includes several important steps. The first is checking out your code:

- name: Checkout
  uses: actions/checkout@v4

This step uses an existing action from GitHub ( actions/checkout@v4) to check out your code from the repository. This is the foundation of what makes all other operations possible. This fetches your code and makes it available to the workflow for building and testing. Then, the workflow determines the default scheme:

- name: Set Default Scheme
  run: |
    scheme_list=$(xcodebuild -list -json | tr -d "\n")
    default=$(echo $scheme_list | ruby -e "require 'json'; puts JSON.parse(STDIN.gets)['project']['targets'][0]")
    echo $default | cat >default
    echo Using default scheme: $default

This step extracts the default scheme from your Xcode project and stores it in a file called default. This automates the selection of which build scheme to use. The script queries your project's Xcode settings and extracts the scheme, so the workflow knows which to build and test. Then comes the build step:

- name: Build
  env:
    scheme: ${{ 'default' }}
    platform: ${{ 'iOS Simulator' }}
  run: |
    # xcrun xctrace returns via stderr, not the expected stdout (see https://developer.apple.com/forums/thread/663959)
    device=`xcrun xctrace list devices 2>&1 | grep -oE 'iPhone.*?[^\(]+' | head -1 | awk '{$1=$1;print}' | sed -e "s/ Simulator$//"`
    if [ $scheme = default ]; then scheme=$(cat default); fi
    if [ "`ls -A | grep -i \.xcworkspace{{content}}quot;`