Tophat by Shopify

Product Introduction

1. Definition: Tophat by Shopify is a macOS desktop application (a native SwiftUI app) that functions as a mobile development artifact installer and testing platform. It is a developer tool specifically engineered for iOS and Android engineers to streamline the process of installing and testing CI/CD build artifacts on simulators and physical devices.
2. Core Value Proposition: Tophat exists to eliminate the time-consuming process of building pull request branches locally. Its primary value is enabling developers to instantly test any Continuous Integration (CI) artifact with a single click, directly on their target device or simulator, thereby accelerating mobile development workflows and code review cycles.

Main Features

1. One-Click Installation via Artifact Providers: Tophat's core functionality is powered by a modular system of artifact providers. These providers are responsible for fetching build artifacts (like .ipa, .apk, or .zip files) from various sources. Built-in providers include a direct HTTP downloader and a customizable shell script executor. The system uses a URL scheme (tophat://install/<provider_id>?parameters) to trigger installations from anywhere, such as GitHub PR comments or internal tools.
2. Quick Launch Menu for Favourite Apps: This feature allows developers to pin frequently tested applications to the Tophat menu bar. Quick Launch icons are not static; Tophat automatically fetches and updates them with the latest available build from the configured artifact provider. This provides a persistent, one-click access point to the most current version of an app without manual URL management.
3. Command Line Interface (tophatctl): Tophat includes a companion CLI tool for advanced automation and integration. tophatctl allows developers to manage Quick Launch apps, install artifacts directly from the terminal, list available artifact providers, and pre-populate Tophat with project apps during development environment setup (e.g., in a dev up script). This bridges GUI convenience with scriptable DevOps workflows.
4. Extensible Architecture with TophatKit SDK: For teams with custom build or caching systems, Tophat offers the TophatKit SDK. This allows engineering teams to develop proprietary extensions, creating custom artifact providers that integrate seamlessly with internal toolchains like Bazel, Buck, or proprietary artifact repositories, ensuring compatibility with virtually any development environment.
5. Multi-Recipe & Device-Aware Installation: A single Tophat URL can contain multiple "recipes." This is crucial for supporting both simulators and physical devices from one link, as they often require different build variants (e.g., simulator vs. device SDK). Tophat intelligently selects the correct artifact based on the platform (ios/android) and destination (simulator/device) parameters specified in the URL or chosen by the user in the app.

Problems Solved

1. Pain Point: Wasting hours cloning repositories, checking out branches, resolving local dependencies, and building mobile applications locally just to test a single Pull Request (PR) or CI build. This context-switching and wait time severely disrupts developer flow and slows down review processes.
2. Target Audience: The primary users are iOS Engineers and Android Engineers working in teams with established CI/CD pipelines. Secondary users include QA Engineers who need to install specific builds for testing, and Engineering Managers seeking to optimize their team's development velocity and PR review efficiency.
3. Use Cases:
   • PR Review Testing: A reviewer can click a "Install with Tophat" link in a GitHub PR description to instantly test the proposed changes on their own simulator or device without any local setup.
   • QA Build Distribution: QA teams can receive a single Tophat link to install the latest beta build on a suite of pinned physical devices for regression testing.
   • Demoing Latest Builds: Product managers or stakeholders can use a Quick Launch icon to always launch the most recent staging build for demos.
   • Onboarding & Development Environment Setup: tophatctl can be used in project setup scripts to automatically add the team's core apps to a new developer's Tophat Quick Launch.

Unique Advantages

1. Differentiation: Unlike generic mobile device management (MDM) solutions or manual .ipa/.apk side-loading, Tophat is purpose-built for the developer workflow, integrating directly with CI systems and code hosting platforms. Compared to other internal tooling, its extensible provider model and first-class CLI support offer more flexibility than simple download scripts.
2. Key Innovation: The artifact provider abstraction is its core innovation. By decoupling the installation engine from the artifact source, Tophat can support a universal installation interface (tophat:// URLs) while allowing the underlying fetch logic to be customized for Google Cloud Storage, GitHub Actions, AWS S3, or any internal system via extensions. This makes it a versatile hub for all mobile artifact installation needs.

Frequently Asked Questions (FAQ)

1. What CI systems does Tophat by Shopify work with? Tophat works with any CI system that can produce a publicly accessible or internally accessible mobile build artifact (.ipa, .apk). It uses artifact providers to fetch from these systems; built-in providers handle HTTP downloads and custom shell scripts, while extensions can be built for specific CI platforms like GitHub Actions, CircleCI, or Jenkins.
2. Is Tophat by Shopify free to use? Yes, Tophat is a free, open-source tool released by Shopify under the MIT license. The source code is available on GitHub, and signed application binaries are provided in the releases section for direct download and use.
3. Can I use Tophat to install apps on physical iPhones and Android devices? Yes, Tophat supports installation on both iOS simulators and physical iOS devices (running iOS 17+) via ios-deploy, and on Android emulators and physical Android devices via the adb (Android Debug Bridge) toolchain. The app guides you through setting up the necessary developer tools on first launch.
4. How do I create an "Install with Tophat" link for my GitHub Pull Requests? You need to generate a tophat:// URL using your artifact provider's parameters. For example, using the built-in HTTP provider: tophat://install/http?url=<YOUR_BUILD_ARTIFACT_URL>. You can add this link to your PR template or have your CI pipeline post it as a comment. For advanced use, you can create a GitHub Actions workflow that automatically comments with the Tophat link on each new build.
5. What are the system requirements for running Tophat? Tophat requires macOS 15 (Sequoia) or later. For iOS development, Xcode 15 or newer is required. For Android development, a working Android toolchain with adb and avdmanager accessible from the terminal is needed.