Any iOS pull request.
In Simulator. One click.
Set up one repository and each reviewer's Mac. Then every pull request gets a Run in Simulator button.
Getting started
Do these steps once. Your first preview can be ready in about five minutes.
- Connect a repository
Sign in with GitHub. Choose the iOS repository in your workspace.
- Add the workflow
Use the shared Xcode scheme that builds your app for Simulator.
- Prepare each Mac
Install SimPreview and Xcode. Open the Mac app and sign in with GitHub.
You are ready. Open a pull request and select Run in Simulator.
Workflow
Add this file at .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: MyAppXcode Cloud & other CI
Use a publish token when GitHub Actions does not build your app.
- 1
Create a token on the repository page in your SimPreview workspace.
- 2
Store the token in CI as
SIMPREVIEW_TOKEN. - 3
Add
ci_scripts/ci_post_xcodebuild.shwith this content.
#!/bin/sh
curl -fsSL https://simpreview.digitalbunker.dev/publish.sh | bashSecurity
Keep access limited to the people and repositories that need it.
- Choose only the repositories that may publish previews.
- Ask each reviewer to use their own GitHub account.
- Remove a repository or token from the workspace when it is no longer needed.
Troubleshooting
Start with the message shown in CI, the preview page, or the Mac app.
No Run button
Check that the pull request workflow finished. Confirm that its scheme is shared.
The app will not open
Install the iOS runtime named on the preview page. Then choose a matching Simulator.
The preview is no longer available
Run the pull request workflow again. Open the updated link in the pull request.