Contribute an app

The Awesome List is a curated collection of apps with downloadable IPA releases. Suggest an app by opening a pull request with an entry, its icon source URL, and attribution. You do not need to add image files or edit the website's React components or generated documentation.

Add an entry

After setting up the repository, add an object to docs/awesome-apps.json. Use an existing entry as a starting point:

json
{
    "id": "utm",
    "title": "UTM",
    "description": "Run virtual machines on your iPhone, iPad, or Vision Pro with UTM SE.",
    "repo": "utmapp/UTM",
    "website": "https://getutm.app",
    "iconSource": "https://raw.githubusercontent.com/utmapp/UTM/COMMIT_SHA/Platform/Assets.xcassets/AppIcon.appiconset/Icon.png",
    "license": {
        "name": "Apache-2.0; bundled components have other licenses",
        "url": "https://github.com/utmapp/UTM/blob/main/LICENSE"
    },
    "installs": [
        {"platforms": ["iphone", "ipad"], "filter": "^UTM-SE$"},
        {"platforms": ["visionos"], "filter": "^UTM-SE-visionOS$"}
    ]
}

Replace COMMIT_SHA with the full 40-character commit hash containing the icon. IDs, repositories, and platform defaults must be unique. Unknown fields are rejected so a misspelled filter cannot silently change the generated command.

FieldWhat to provide
idA stable lowercase slug, such as my-app
titleThe app's name, up to 80 characters
descriptionPlain text describing what the app does, up to 300 characters; searchable on the list
repoThe public GitHub owner/repository that publishes the IPA
websiteOptional HTTPS URL for the project's official website
iconSourceThe upstream raw.githubusercontent.com URL, pinned to a commit in that repository
licenseThe license name and a link to its file in the repository; describe custom or mixed licensing accurately
installsPlatform groups and the default filename filter for each group
featuredOptional boolean; maintainers select which icons appear on the landing page

Choose a useful default

An install option contains platforms, filter, and optionally release. Omit release to track the latest stable release. Use prerelease for the newest prerelease, or a tag to select a specific release.

Supported platform values are iphone, ipad, appletv, visionos, and applewatch. Include only platforms supported by that particular IPA, based on the project's documentation and your testing. Each platform can appear in only one option for an app. Use separate options when different platforms need different IPA files.

The filename filter must match exactly one IPA in the selected release. Matching is case-insensitive. Text such as tv matches anywhere; advanced*tv matches separated text segments. A filter beginning with ^ or ending with $ uses a regular expression. Names are checked without the .ipa suffix first. Prefer stable parts of filenames rather than version numbers.

Choose builds intended for ordinary re-signing where possible. Describe any additional setup in your pull request: re-signing alone does not enable JIT or satisfy every entitlement requirement. Apps without a published IPA are not included.

Provide the icon source and attribution

Point iconSource at a square PNG between 128 and 2048 pixels on each side, no larger than 5 MB. Validation and website builds fetch missing icons automatically: first from https://ipa-hub.giladgd.com/assets/awesome-apps/<id>.webp, then from iconSource if the published image is unavailable or invalid. If neither works, the build fails.

Downloaded icons are cached as assets/awesome-apps/<id>.webp. This directory is gitignored, and subsequent builds reuse its files without downloading them again. Remove a cached file to fetch it again. Attribution files remain tracked separately.

Create assets/licenses/awesome-apps/<id>.txt with the app name, the exact iconSource URL, the exact license URL, and the applicable upstream license and attribution notices. Check whether artwork has separate terms and preserve those too. The website publishes these notices alongside the icons. Do not add artwork you are not permitted to redistribute.

Validate and open a pull request

npm run validate:awesome
npm run validate:awesome -- --check-releases

The first command checks the JSON, duplicate entries, platform defaults, icons, and attribution files, downloading any missing icons. The second also checks GitHub releases using the same filename matcher as ipa-hub install. Each default filter must select exactly one uploaded IPA. Set the GITHUB_TOKEN environment variable if you encounter GitHub's unauthenticated rate limit; never put a token in the catalog or pull request.

CI runs both checks. Normal documentation and website builds validate the catalog and fetch missing icons without fetching GitHub releases. To preview your change, run npm run dev:website and open the Awesome List from the version menu.

In your pull request, describe what the app does, link to the release, and list the devices and OS versions you tested. Maintainers review suitability, platform support, and licensing before merging. CI checks the catalog and release assets; it does not run or endorse the apps.

Edit this page