GitHub Actions for iOS

Build an iOS Simulator App with GitHub Actions

Add a small GitHub Actions job that gives each iOS pull request a Simulator preview.

5 minute readUpdated September 3, 2026

Check your Xcode project

Open the scheme menu in Xcode and make sure the app scheme is shared. Commit the scheme file with the project.

If the repository has more than one project or workspace, note which one contains the app.

Add the pull request job

Create .github/workflows/simpreview.yml. Replace MyApp with your shared scheme.

name: SimPreview

on:
  pull_request:

permissions:
  contents: read
  id-token: write
  pull-requests: read

jobs:
  preview:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v5
      - uses: aryamansharda/simpreview-build@v1
        with:
          scheme: MyApp

Open the first preview

Push the workflow on a pull request. Wait for the SimPreview job to finish. Then select Run in Simulator in the pull request.

If the scheme is not found, mark it as shared in Xcode and commit the change.

Next: Check common setup problems

COMMON QUESTIONS

What teams ask

Does a Simulator build need code signing?

No. Device and App Store builds have different signing needs.

Should I use Debug or Release?

Use the setting that best matches the feature under review. Debug is a good default.

Can I use an existing build step?

Yes. Pass its .app path to SimPreview with app-path.

ADD THE PREVIEW JOB

Create a workflow for your app.

Choose your repository and shared scheme. Then add the result to GitHub Actions.

Create the workflow