{"id":21824351,"url":"https://github.com/shopify/tophat","last_synced_at":"2025-05-15T08:10:17.974Z","repository":{"id":253861531,"uuid":"843554833","full_name":"Shopify/tophat","owner":"Shopify","description":"Easily install and test mobile applications with a single click.","archived":false,"fork":false,"pushed_at":"2025-04-30T16:22:11.000Z","size":5612,"stargazers_count":768,"open_issues_count":4,"forks_count":27,"subscribers_count":75,"default_branch":"main","last_synced_at":"2025-05-11T09:16:50.206Z","etag":null,"topics":["android","ios","productivity","swift","swiftui","xcode"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shopify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-16T19:19:52.000Z","updated_at":"2025-04-30T20:43:30.000Z","dependencies_parsed_at":"2024-11-07T18:21:07.267Z","dependency_job_id":"2cde75e0-cb3b-498a-a0a7-e823bf07cfe9","html_url":"https://github.com/Shopify/tophat","commit_stats":null,"previous_names":["shopify/tophat"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Ftophat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Ftophat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Ftophat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Ftophat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shopify","download_url":"https://codeload.github.com/Shopify/tophat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301433,"owners_count":22047904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","ios","productivity","swift","swiftui","xcode"],"created_at":"2024-11-27T17:57:41.774Z","updated_at":"2025-05-15T08:10:17.941Z","avatar_url":"https://github.com/Shopify.png","language":"Swift","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"./media/icon.png\" alt=\"Tophat\" width=\"128\"\u003e\n  \u003cbr\u003e\n  Tophat \n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  As seen on the \u003ca href=\"https://shopify.engineering/shopify-tophat-mobile-developer-testing\"\u003eShopify Engineering Blog\u003c/a\u003e!\n\u003c/p\u003e\n\n![Artwork](/media/banner.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTophat is the best way to install and test any mobile application. Just add CI.\u003c/strong\u003e\n\u003c/p\u003e\n\n### One-Click Installation\n\nWith Tophat, you can skip building branches locally. Use Tophatʼs many features and APIs to easily create installation links to CI artifacts. Take your tooling a step further and offer contributors the ability to test pull requests without cloning anything!\n\n### Extensions\n\nWith the [TophatKit](./TophatKit) SDK, you can easily extend Tophat to integrate with custom build and caching systems. This makes Tophat compatible with virtually any tooling setup you can imagine!\n\n### Quick Launch\n\nQuick Launch allows you to add your favourite apps right to the Tophat menu. Need the latest build? Click on the icon and go! Tophat will download the latest version, automatically update the icon, and launch it on your device.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./media/quick_launch.png\" alt=\"Quick Launch\" width=\"429\"\u003e\n\u003c/p\u003e\n\n\n### Device Pinning\n\nHave lots of devices and only use a couple at a time? Easily pin them to the top of the devices list for quick access.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./media/device_pinning.png\" alt=\"Device Pinning\" width=\"588\"\u003e\n\u003c/p\u003e\n\n### Customize\n\nCustomize Tophat to your needs with the Settings window. Adjust preferences, add apps to Quick Launch, or even specify custom tooling paths to make Tophat work for your environment.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./media/settings.png\" alt=\"Settings\" width=\"713\"\u003e\n\u003c/p\u003e\n\n## Integrating Tophat\n\n\u003e :bulb: The following APIs have been introduced in Tophat 2. Legacy APIs have been removed.\n\nDownloads with Tophat are powered by **_artifact providers_**. Some providers are built-in to Tophat, while some can be installed using Tophat Extensions (see [_Extensions_](#extensions)). When triggering an install with Tophat, you will need to specify the following information:\n\n- The providerʼs ID.\n- The providerʼs parameters.\n- The platform (optional).\n- The destination (optional).\n- A list of launch arguments (optional).\n\nThe format by which this information is specified varies slightly depending on whether you use URLs, Quick Launch, or `tophatctl`, but each API requires roughly the same information.\n\nYou can view a list of all artifact provider IDs using `tophatctl list providers`.\n\nEach request can install multiple artifacts. Within each request, these are called _recipes_, and are particularly useful when you want to have one link that supports both simulators and devices in the same link, where different builds are required for each.\n\n### URLs\n\nTophat handles URLs using both the `tophat://` and `http://` schemes so that you can use them in any website or application. Where possible, prefer the `tophat://` scheme which does not navigate away from the current page.\n\nThe examples below will use `tophat://`, but `tophat://` is interchangeable with `http://localhost:29070/` for use with GitHub, for example.\n\n\u003e :memo: When creating an install link, prefer using “Install with Tophat” as the link text.\n\n#### URL Format\n\nBelow is an example for a hypothetical artifact provider for Google Cloud Storage. In this case, `gcs` is the artifact provider ID:\n\n```\ntophat://install/gcs?bucket=\u003cbucket\u003e\u0026object=\u003cobject\u003e\n```\n\nThe type of build downloaded will be interpreted by Tophat automatically, but the API provides a means to preheat the intended device ahead of time by specifying the platform and destination:\n\n```\ntophat://install/gcs?bucket=\u003cbucket\u003e\u0026object=\u003cobject\u003e\u0026platform=ios\u0026destination=device\n```\n\nIf multiple artifacts are created for different destinations, parameters for both artifacts may be specified in the same URL by repeating query parameters. Tophat will then select the appropriate parameters for the selected device.\n\n```\ntophat://install/gcs?bucket=\u003cbucket\u003e\u0026object=\u003cobject\u003e\u0026platform=ios\u0026destination=device\u0026bucket=\u003cbucket\u003e\u0026object=\u003cobject\u003e\u0026platform=ios\u0026destination=simulator\n```\n\nLaunch arguments may be specified using the `arguments` query parameter:\n\n```\ntophat://install/gcs?bucket=\u003cbucket\u003e\u0026object=\u003cobject\u003e\u0026arguments=one,two,three\n```\n\nOn iOS, these arguments are retrievable using `ProcessInfo`. On Android, these arguments are delivered to your appʼs main activity _via_ intent argument extras in the `TOPHAT_ARGUMENTS` key as an array of strings.\n\n## Using Tophat\n\n### Core Providers\n\nSome core providers are built-in to Tophat. These provide a balance between ease of use and flexibility.\n\n#### Basic HTTP\n\n```\ntophat://install/http?url=\u003cfull_public_url\u003e\n```\n\n#### Shell Script\n\nA shell script allows you to have full control over how the artifact is downloaded. Shell scripts are placed in `~/Library/Application Scripts/com.shopify.Tophat.TophatCoreExtension/` and must have their executable flags set with `chmod +x \u003cfilename\u003e`.\n\nFor example, a shell script with filename `filename` placed in the location described above can be invoked using:\n\n```\ntophat://install/shell?script=filename\n```\n\nThe script is provided with two positional arguments:\n\n- `$1` is a full path to a **staging** directory where you may temporarily store files during download and unzip.\n- `$2` is a full path to the **output** directory where exactly one artifact must be located when the script finishes. Tophat will look in this directory to install the application.\n\n### Command Line Helper\n\nTophat can be integrated with various tools and projects using `tophatctl`, Tophatʼs companion command line app. You can use `tophatctl` to perform the following tasks:\n\n- **Manage Quick Launch apps.** Pre-populate Tophat with your projectʼs apps in a `dev up` step.\n- **Install apps.** Install an app by URL or path.\n- **List providers.** Display provider configuration to assist with integration.\n\nFor more details on how to use `tophatctl`, run the following command after installing the Command Line Helper:\n\n```sh\ntophatctl --help\n```\n\n### File Associations\n\nTophat also adds file associations to `*.ipa`, `*.apk`, and `*.zip` files so you can open artifacts from your device.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./media/open_with.png\" alt=\"Open With\" width=\"556\"\u003e\n\u003c/p\u003e\n\n## Getting Started\n\nA signed universal binary of Tophat can be downloaded from the latest GitHub release. Click the button below to jump to it, download the `.zip` file, and move Tophat to your Applications folder:\n\n[![Latest GitHub Release](https://img.shields.io/github/v/release/Shopify/tophat?color=black\u0026label=download%20latest\u0026logo=github\u0026sort=semver\u0026style=for-the-badge)](https://github.com/Shopify/tophat/releases/latest)\n\nA full list of releases is available [here](https://github.com/Shopify/tophat/releases).\n\nTophat will automatically check for updates and let you know if a new one is available. Youʼll be prompted to enable automatic update checks the second time you launch Tophat. Automatic updates can also be configured from Tophatʼs Settings window.\n\nTophat requires a few developer tools to be set up. On first launch, Tophat will guide you through making sure everything you need is ready to go.\n\n## Requirements\n\nTophat requires macOS 14 or later.\n\n### iOS Development\n\n- Xcode 15 or newer is required.\n- All simulator versions are supported, but physical devices must be running iOS 17 or later.\n\n### Android Development\n\nTophat works with Android Studio and Android toolchains with a working `adb` and `avdmanager` environment.\n\n## Contributing\n\nSee the [contribution guidelines](CONTRIBUTING.md) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopify%2Ftophat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshopify%2Ftophat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshopify%2Ftophat/lists"}