Mattermost Logo
We're hiring!
Edit on GitHub

Building an iOS Mattermost App

At times, you may want to build your own Mattermost mobile app. The most common use cases are:

  • To white label the Mattermost mobile app.
  • To use your own deployment of the Mattermost Push Notification Service (always required if you are building your own version of the mobile app).

Build Preparations 

1. Prerequisites 

The Mattermost mobile app for iOS needs to be built on a macOS computer with Xcode and the Xcode command line tools installed.

$ xcode-select --install

2. Bundle ID and entitlements 

  • Follow the steps 1, 2, and 3 for Run on iOS Devices in the Developer Setup.
  • After configuring the app in the previous step, ensure the bundle ID for each target of the mobile app remains the same as the one in the original mattermost-mobile GitHub repository (com.mattermost.rnbeta, com.mattermost.rnbeta.MattermostShare, and com.mattermost.rnbeta.NotificationService).

3. Code signing 

Apple requires all apps to be digitally signed with a certificate before they can be installed.

The build script will make use of Match to sync your provisioning profiles (the profiles will be created for you if needed). The provisioning profiles will be created based on the environment variables.

4. Configure Environment Variables 

To make it easier to customize your build, we’ve defined a few environment variables that are going to be used by Fastlane during the build process.

Variable Description Default Required
COMMIT\_CHANGES\_TO\_GIT Should the fastlane script ensure that there are no changes to Git before building the app and that every change made during the build is committed back to Git.

Valid values are: true, false
false No
BRANCH\_TO\_BUILD Defines the Git branch that is going to be used for generating the build.

Make sure that, if this value is set, the branch it is set to exists.
GIT\_LOCAL\_BRANCH Defines the local branch to be created from BRANCH_TO_BUILD to ensure the base branch does not get any new commits on it.

Make sure a branch with this name does not yet exist in your local git.
build No
RESET\_GIT\_BRANCH Defines if, once the build is done, the branch should be reset to the initial state before building and whether to also delete the branch created to build the app.

Valid values are: true, false
false No
VERSION\_NUMBER Set the version of the app at build time to a specific value, rather than using the one set in the project. No
INCREMENT\_VERSION\_<br>NUMBER\_MESSAGE Set the commit message when changing the app version number. Bump app version number to No
INCREMENT\_BUILD\_NUMBER Defines if the app build number should be incremented.

Valid values are: true, false
false No
BUILD\_NUMBER Set the build number of the app at build time to a specific value, rather than incrementing the last build number. No
INCREMENT\_BUILD\_<br>NUMBER\_MESSAGE Set the commit message when changing the app build number. Bump app build number to No
APP\_NAME The name of the app as it is going to be shown in the device home screen. Mattermost Beta Yes
APP\_SCHEME The URL naming scheme for the app as used in direct deep links to app content from outside the app. mattermost No
REPLACE\_ASSETS Override the assets as described in White Labeling.

Valid values are: true, false
false No
MAIN\_APP\_IDENTIFIER The bundle identifier for the app. Yes
BUILD\_FOR\_RELEASE Defines if the app should be built in release mode.

Valid values are: true, false

Make sure you set this value to true if you plan to submit this app to TestFlight, the Apple App Store or distribute it in any other way.
false Yes
NOTIFICATION\_SERVICE\_IDENTIFIER The bundle identifier for the notification service extension. Yes
EXTENSION\_APP\_IDENTIFIER The bundle identifier for the share extension. Yes
FASTLANE\_TEAM\_ID The ID of your Apple Developer Portal Team. Yes
IOS\_ICLOUD\_CONTAINER The iOS iCloud container identifier used to support iCloud storage. Yes
IOS\_APP\_GROUP The iOS App Group identifier used to share data between the app and the share extension. Yes
SYNC\_PROVISIONING\_PROFILES Should we run match to sync the provisioning profiles. Note: Not syncing the provisioning profiles, will cause the singing to fail. Valid values are: true, false false Yes
MATCH\_USERNAME Your Apple ID Username. Yes
MATCH\_PASSWORD Your Apple ID Password. Yes
MATCH\_KEYCHAIN\_PASSWORD Your Mac user password used to install the certificates in the build computer KeyChain. No
MATCH\_GIT\_URL URL to the Git repo containing all the certificates.

Make sure this Git repo is set to private. Remember this repo will be used to sync the provisioning profiles and other certificates.
MATCH\_APP\_IDENTIFIER The Bundle Identifiers for the app (comma-separated).

List the identifiers for each target of the app.
for example:
MATCH\_TYPE Define the provisioning profile type to sync. Valid values are: appstore, adhoc, development, enterprise

Make sure you set this value to the same type as the IOS\_BUILD\_EXPORT\_METHOD as you want to have the same provisioning profiles installed in the machine so they are found when signing the app.
adhoc Yes
SUBMIT\_IOS\_TO\_TESTFLIGHT Submit the app to TestFlight once the build finishes. Valid values are: true, false false No
PILOT\_USERNAME Your Apple ID Username used to deploy the app to TestFlight. No
PILOT\_SKIP\_WAITING\_<br>FOR\_BUILD\_PROCESSING Do not wait until TestFlight finishes processing the app.

Valid values are: true, false
true No


To configure your variables create the file ./mattermost-mobile/fastlane/.env where .env is the filename. You can find the sample file env_vars_example here.

Building the App 

Once all the previous steps are complete, execute the following command from within the project’s directory:

$ npm run build:ios

This will start the build process following the environment variables you’ve set. Once it finishes, it will create an .ipa file with the APP_NAME as the filename in the project’s root directory. If you have not set Fastlane to submit the app to TestFlight, you can use this file to manually publish and distribute the app.