App Previews

Share your iOS apps instantly with QR codes and web links

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

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

Creating Previews

From Command Line

1. Build your app

   Build your project for the desired platform:

   # Build for iOS
   tuist build --platform iOS --configuration Release
   
2. 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
3. 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

# Development track
tuist share --track dev

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

# Beta track  
tuist share --track beta

Environments

# Staging environment
tuist share --track staging

# Production preview
tuist share --track production

Teams

# 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

1. Open the preview link

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

2. Install the profile

   Tap “Install” to add the app installation profile

3. Trust the profile

   Go to Settings > General > VPN & Device Management

   Trust the Tuist profile

4. 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

1. Open the preview link

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

2. Download the APK

   Chrome/Browser will download the .apk file

3. Allow installation

   Enable “Install from unknown sources” if prompted

4. 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:

GitHub Actions

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/...)'
            })

previews:
  stage: deploy
  script:
    - curl -Ls https://install.tuist.io | bash
    - tuist build --platform iOS --configuration Release
    - tuist share --track $CI_COMMIT_REF_SLUG
  only:
    - merge_requests
  variables:
    TUIST_TOKEN: $TUIST_TOKEN

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 iPad

iOS 13.0+

tvOS

Apple TV

tvOS 13.0+

watchOS

Apple Watch

watchOS 6.0+

visionOS

Apple Vision Pro

visionOS 1.0+

macOS

Mac computers

macOS 11.0+

Android

Android devices

Android 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