Skip to content

Xcode previews

Build your application, then use tuist share to publish it to your Tuist project. Connect your project first using the existing Xcode project or generated project guide.

Build and share#

For a Tuist-generated project:

bash
tuist generate App
tuist xcodebuild build -scheme App -workspace App.xcworkspace \
-configuration Debug -sdk iphonesimulator
tuist share App

For an existing Xcode project:

bash
tuist xcodebuild build -scheme App -project App.xcodeproj \
-configuration Debug -sdk iphonesimulator
tuist share App --configuration Debug --platforms iOS

Replace the scheme, project, and workspace names with your own. To share a Release build, use -configuration Release when building and --configuration Release when sharing.

Physical devices#

You are responsible for signing device builds with a provisioning profile that allows installation on the recipient's device. Build with a device destination instead of the simulator SDK:

bash
tuist xcodebuild build -scheme App -project App.xcodeproj \
-configuration Debug -destination 'generic/platform=iOS'
tuist share App --configuration Debug --platforms iOS

You can also share an already exported IPA:

bash
tuist share App.ipa

Recipients can open an IPA preview link on their mobile device to install the application. Authentication and the project's preview visibility still apply.

CI and build numbers#

Use your existing CI authentication and make CFBundleVersion unique for each new build. For example, use GitHub Actions' ${{ github.run_number }}. Uploading the same binary and build number again through tuist share fails rather than creating a duplicate.

bash
tuist share App --track beta --release-notes "Fix sign-in"

See Run a preview for running published builds, access, tracks, and README badges.

Tracks with tuist share#

For workflows that publish with tuist share, use --track to select a track:

bash
tuist share App --track beta
tuist share App --track nightly

Release notes#

Use tracks for environment groups and release notes for the purpose of an individual build:

bash
tuist share App --track QA --release-notes "Fix sign-in and improve the checkout flow"

Replace App with your app name, application file path, or executable distribution and its --executable option. Release notes are optional plain text, up to 10,000 characters. The first nonblank line appears as a single-line snippet in preview lists, so build numbers and other identifying information are visible at a glance. Long lines are truncated; full notes appear on the detail pages. Search matches display names and full release notes, including lines not shown in the snippet. Multiline notes are supported, for example --release-notes "$(< release-notes.txt)". They do not change the app's display name or its track.

Compatibility#

Release notes don't change which preview a build belongs to. The first notes a preview receives are kept: a later upload can add notes to a preview that has none, but can't overwrite or clear existing ones. Previews uploaded before release notes existed stay valid without them.

Self-hosted deployments need a server version that supports release notes and track filtering, together with an updated client. Older servers ignore the notes. For the track and search filters of the list endpoints, see the API reference.

Pull/merge request comments#

Git forge integration required

To get automatic pull/merge request comments, integrate your remote project with a Git forge: GitHub, Cursor Origin, or Entire.

Once your Tuist project is connected with your Git platform, add tuist share after a successful application build in CI. Tuist will post a preview link directly in your pull/merge requests, so reviewers can test without building locally:

GitHub app comment with a Tuist Preview link

Automations#

Use --json to get JSON output from tuist share:

bash
tuist share --json

Use the result for custom automations, such as posting a Slack message from CI. The url key contains the full preview link; qrCodeURL points to a QR code image for opening the preview on a device:

json
{
"id": 1234567890,
"url": "https://tuist.dev/preview/1234567890",
"qrCodeURL": "https://tuist.dev/preview/1234567890/qr-code.svg"
}

Recipients can use the Tuist macOS app or iPhone app independently of the build-system integration. The iPhone guide also covers in-app update notifications with the Tuist SDK.