App Previews

Tuist App Previews allow you to share your iOS, tvOS, watchOS, visionOS, and Android apps with teammates, stakeholders, or testers without going through App Store or TestFlight distribution.

Overview

App Previews provide:

Instant sharing - Generate shareable links and QR codes in seconds
No provisioning hassles - Tuist handles all the complexity
Multi-platform support - iOS, tvOS, watchOS, visionOS, and Android
Track-based distribution - Organize previews by branch, environment, or purpose
Version management - Keep historical versions accessible

Previews are perfect for design reviews, stakeholder demos, and QA testing without App Store distribution.

How It Works

Build your app with Tuist or Xcode
Upload the .ipa or .apk to Tuist Cloud
Share the generated link or QR code
Install directly on devices

Creating Previews

From Command Line

Build your app

Build your project for the desired platform:

# Build for iOS
tuist build --platform iOS --configuration Release

Share the app

Upload and create a preview:

tuist share

Tuist will:

Find the built .ipa in your derived data
Upload it to Tuist Cloud
Generate a shareable link and QR code

Distribute the link

Share the preview URL with your team:

✓ Preview created successfully!

🔗 https://tuist.dev/acme/myapp/previews/abc123
📱 Scan QR code to install

Specify App Path

If you have multiple apps or a custom build location:

# Share specific .ipa file
tuist share MyApp.ipa

# Share .apk for Android
tuist share MyApp.apk

# Share from custom derived data path
tuist share --derived-data-path ~/CustomDerivedData

Multiple Platforms

Share apps for multiple platforms at once:

# Share iOS and tvOS builds
tuist share --platforms iOS tvOS

# Share specific configuration
tuist share --configuration Release --platforms iOS

Tracks

Tracks allow you to organize previews by purpose, environment, or git branch.

Feature Branches
Environments
Teams

# Development track
tuist share --track dev

# Feature track
tuist share --track feature/new-ui

# Beta track  
tuist share --track beta

# Staging environment
tuist share --track staging

# Production preview
tuist share --track production

# Design team
tuist share --track design-review

# QA team
tuist share --track qa

Each track maintains its own preview history, making it easy to manage multiple distribution channels.

Installing Previews

iOS, tvOS, watchOS, visionOS

Open the preview link

Tap the link on your iOS device or scan the QR code

Install the profile

Tap “Install” to add the app installation profile

Trust the profile

Go to Settings > General > VPN & Device ManagementTrust the Tuist profile

Launch the app

The app appears on your home screen, ready to use!

First-time installation requires trusting the Tuist enterprise profile. This is a one-time setup per device.

Android

Open the preview link

Tap the link on your Android device or scan the QR code

Download the APK

Chrome/Browser will download the .apk file

Allow installation

Enable “Install from unknown sources” if prompted

Install the app

Open the downloaded .apk and follow installation prompts

Preview Management

View Previews

List all previews for your project in the Tuist Cloud dashboard:

tuist project show

Or visit https://tuist.dev/your-account/your-project/previews

Preview Information

Each preview includes:

Build version and bundle identifier
Git commit information (if available)
Supported platforms (iOS, tvOS, watchOS, visionOS, Android)
Created by and creation date
QR code for easy device installation
Download link for the binary

Delete Previews

Previews are automatically managed, but you can delete them from the dashboard if needed.

CI/CD Integration

Automatic Preview Creation

Create previews automatically in your CI pipeline:

name: Create Preview
on:
  pull_request:
    branches: [main]

jobs:
  preview:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Build and create preview
        run: |
          tuist build --platform iOS --configuration Release
          tuist share --track pr-${{ github.event.pull_request.number }}
        env:
          TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}
      
      - name: Comment preview link
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🚀 Preview ready! Install from: [Preview Link](https://tuist.dev/...)'
            })

Preview Link in PR Comments

Automatically post preview links to pull requests so reviewers can test changes immediately.

Advanced Features

Git Integration

Previews automatically capture git metadata:

Commit SHA - Which commit the preview was built from
Branch name - The git branch
Commit message - For context

Preview Analytics

Track preview usage in the Tuist Cloud dashboard:

Number of installations
Unique devices
Installation success rate

Icon Customization

Previews display your app icon automatically. The icon is extracted from your app bundle.

Best Practices

Use tracks strategically

Use main track for production-ready builds
Use dev track for internal testing
Use PR numbers or feature names for feature previews
Keep track names descriptive and consistent

Automate in CI

Create previews automatically on PR creation
Post preview links as PR comments
Clean up old previews to save storage
Use separate tracks per environment

Communicate with stakeholders

Include installation instructions in links
Mention supported platforms
Provide context about what’s changed
Use QR codes for quick device installation

Platform Support

iOS

iPhone and iPadiOS 13.0+

tvOS

Apple TVtvOS 13.0+

watchOS

Apple WatchwatchOS 6.0+

visionOS

Apple Vision ProvisionOS 1.0+

macOS

Mac computersmacOS 11.0+

Android

Android devicesAndroid 6.0+

Troubleshooting

Preview upload fails

Possible causes:

Network connectivity issues
File too large (max 2GB)
Authentication expired

Solutions:

Check your internet connection
Verify tuist auth is current
Try uploading a smaller build

Can't install on device

Possible causes:

Profile not trusted
Device storage full
Incompatible iOS version

Solutions:

Trust the profile in Settings
Free up device storage
Check minimum iOS version

QR code doesn't work

Possible causes:

Camera doesn’t recognize QR codes
Need to use Safari/Chrome

Solutions:

Manually type the preview URL
Use the Camera app (iOS) or Chrome (Android)
Copy the link instead

Next Steps

Automated QA

Test previews automatically with AI-powered QA

Build Insights

Monitor preview build times and success rates

​Overview

​How It Works

​Creating Previews

​From Command Line

​Specify App Path

​Multiple Platforms

​Tracks

​Installing Previews

​iOS, tvOS, watchOS, visionOS

​Android

​Preview Management

​View Previews

​Preview Information

​Delete Previews

​CI/CD Integration

​Automatic Preview Creation

​Preview Link in PR Comments

​Advanced Features

​Git Integration

​Preview Analytics

​Icon Customization

​Best Practices

​Platform Support

iOS

tvOS

watchOS

visionOS

macOS

Android

​Troubleshooting

​Next Steps

Automated QA

Build Insights

Overview

How It Works

Creating Previews

From Command Line

Specify App Path

Multiple Platforms

Tracks

Installing Previews

iOS, tvOS, watchOS, visionOS

Android

Preview Management

View Previews

Preview Information

Delete Previews

CI/CD Integration

Automatic Preview Creation

Preview Link in PR Comments

Advanced Features

Git Integration

Preview Analytics

Icon Customization

Best Practices

Platform Support

Troubleshooting

Next Steps