Mastodon for iOS: official client, five extensions, and a required contributor agreement

Mastodon for iOS targets Mastodon servers only and rejects pull requests aimed at other ActivityPub software

Mastodon for iOS is the official client published by the Mastodon organisation, available on the App Store at apps.apple.com/us/app/mastodon-for-iphone/id1571998974. It is not a third-party client that happens to use the Mastodon API; it comes from the same team that builds the Mastodon server software, and that origin sets hard limits on its scope.

The README states the team does not have bandwidth to ensure compatibility with other server software. Pull requests aimed at that compatibility goal will be closed without being accepted. Users who need a client for any ActivityPub implementation other than Mastodon need a different app, because extending compatibility is not a goal the maintainers will take on.

A blog post from 2021 titled 'Developing an official iOS app for Mastodon' at blog.joinmastodon.org describes the project's origin and is linked from the README for historical background.

Five iOS extensions and a separate SDK extend the main Mastodon Xcode project

The repository holds 29 top-level entries and is more complex than a typical single-target iOS app. The main Mastodon/ directory and Mastodon.xcodeproj/ are accompanied by MastodonSDK/, a standalone module holding the core API and data layer, plus five extensions: NotificationService/, ShareActionExtension/, OpenInActionExtension/, WidgetExtension/ and MastodonIntent/.

NotificationService/ handles push delivery. ShareActionExtension/ enables posting from other apps through the iOS share sheet. OpenInActionExtension/ brings external content into Mastodon. WidgetExtension/ provides home screen widgets, while MastodonIntent/ wires up Siri and Shortcuts support.

Contributors working on push notification behaviour touch a different build target than those working on the timeline view, and both sit outside MastodonSDK/. Two test plan files exist at the top level, AppStoreSnapshotTestPlan.xctestplan and MastodonSDK.xctestplan, separate from each other and from the CI workflow.

Building from source requires Documentation/Setup.md and two notification relay endpoints

App Store users install directly from the listing at id1571998974. For source builds, Documentation/Setup.md is the starting point, since the README links there for the full setup process rather than reproducing it inline.

One file in the repository gives a clear picture of what the build needs before it runs: .env.example at the root.

# Required

# https://<your-domain>/relay-to/development
NotificationEndpointDebug=""

# https://<your-domain>/relay-to/production
NotificationEndpointRelease=""

Both variables are marked Required in the file. NotificationEndpointDebug points to a relay URL for debug builds; NotificationEndpointRelease points to one for production. A developer who configures only the debug relay will have a gap in production builds, because both values must point to a running relay server before that configuration functions. The comment format in .env.example shows the expected URL shape with a placeholder domain and a /relay-to/ path.

App Store deployment steps are in Documentation/Deployment.md, covering the fastlane-based submission process.

UI contributions require core team design review, and most pull requests are not accepted

Contributing to Mastodon for iOS means working within a constraint the README states plainly: 'user interface changes for our official apps are carried out through a design process that involves core team review - most changes of this kind will not be accepted as community contributions; if they are accepted, they will take time to go through this review.'

Notice the phrase 'our official apps' rather than 'this app.' That phrasing covers the full official Mastodon client portfolio, not just iOS, and the policy applies across all of them.

Code contributions that avoid the UI layer pass through a standard pull request workflow. Architecture changes, bug fixes in MastodonSDK/, and extension-level behaviour changes all face a lower barrier than visual redesigns. The iOS-specific contributing guide at Documentation/CONTRIBUTING.md is separate from the general Mastodon contributing guide, which the README also links.

Fastlane, two test plan files, and a build-only CI workflow compose the delivery infrastructure

Deployment automation runs through fastlane/, with a Gemfile and Gemfile.lock at the repository root managing its Ruby dependencies. A .ruby-version file pins the Ruby version for consistency across developer machines. Documentation/Deployment.md documents the App Store submission steps that use this setup.

Continuous integration runs a single workflow named build-only.yml under .github/workflows/, and the README surfaces its status as the CI badge. The workflow's name signals its scope: it checks that the project builds, which is distinct from running the two test plan files, AppStoreSnapshotTestPlan.xctestplan and MastodonSDK.xctestplan, that sit at the top level.

AppVersion.xcconfig at the repository root holds the version configuration separately from the main Xcode project settings, and swiftgen.yml automates code generation for localised strings and other assets.

Every contributor must sign an agreement before a pull request can be accepted

Submitting a pull request to Mastodon for iOS includes a step not present in most open source iOS apps. It carries a GPL-3.0 licence and is dual-licensed to Apple for App Store distribution; the README says 'For this reason, any contributors are required to sign a Contributor License Agreement,' directly connecting that requirement to the dual-licence arrangement with Apple.

No link to the agreement form appears in the README text, and the signing process is not described there. A developer who clones the repository and opens a pull request without first finding and signing it cannot have that work accepted.

Non-UI contributions such as SDK bug fixes and extension changes avoid the core team design review, but they still go through the usual code review and require completing the signing step before submission.

Crowdin manages translations outside the pull request workflow and the repository remains active

Localization runs through Crowdin, configured via crowdin.yml at the repository root. A Crowdin badge in the README links to crowdin.com/project/mastodon-for-ios, where translation progress is visible by language. Translators work in the Crowdin interface rather than opening pull requests, and Localization/ at the repository root stores the resulting string files separately from the Swift source targets.

This setup lets non-iOS developers contribute real value without a full Xcode build environment. Writing Swift, managing the SDK or running fastlane requires the developer setup described in Documentation/Setup.md; submitting a translation in Crowdin does not.

The last push to the repository was on 2026-09-28. Assets and localised strings are generated from swiftgen.yml at the root, which keeps generated code consistent as new strings arrive through the Crowdin workflow.

Editorial conclusion

Mastodon for iOS is the right choice for users who want an officially maintained Mastodon client installable from the App Store without touching any source code. Skip it if you need a client that works across non-Mastodon ActivityPub software: the README explicitly disavows that use case and pull requests aimed at it are closed. Before contributing, read Documentation/CONTRIBUTING.md for the iOS-specific guide and accept that most UI submissions will not pass the design review process, then start with Documentation/Setup.md for the full build setup.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. mastodon/mastodon-ios on GitHub
3. Project website
4. README
5. Releases