Skip to main content
Version: v4 (current)


Setup (only one time per mac)

Install the latest Xcode command line tools :

xcode-select --install

Install fastlane using:

# Using RubyGems
sudo gem install fastlane -NV

# Alternatively using Homebrew
brew install fastlane

Unity Settings

  1. Switch target to iOS
  2. In PlayerSettings -> Other Settings
    1. Fill the field Signing Team ID
    2. Ensure Automatically Sign is unchecked
    3. iOS Provisioning Profile
      1. ProfileID: match AppStore your_bundle_identifier Replace your_bundle_identifier by yours
      2. ProfileType: Distribution

XCode project

Make a first iOS build using your mac from Unity, that will create an xcode project.
Ensure you target the same path as the CI.
Ex: if you let BUILD_NAME: ExampleProjectName in .gitlab-ci.yml, your xcode project must be at the root of the following path: .\Builds\iOS\ExampleProjectName\

App on portal

Make sure that you have setup your app on the Apple Developer Portal and the App Store Connect or use fastlane produce to create it.

Fastlane initialization

Open the terminal at the same path then run fastlane init, follow instructions to generate Appfile and default Fastfile.

Provisioning profile

Run fastlane match init, follow instructions, select appstore provisioning profile type. (Documentation)

Make lane

Copy the following instructions on your fastlane/Fastfile:


platform :ios do
desc "Push a new beta build to TestFlight"
lane :beta do
sync_code_signing(type:"appstore", readonly: is_ci)
build_number: latest_testflight_build_number + 1

Note about upload_to_testflight: Change "Team" to your internal tester or remove (groups:["Team"]) if you want set manually who can test the build

Run tests locally

Run the following command to test the build and the deployement localy:

fastlane ios beta

If the build and upload are ok, you have to force add some file to your git using command below

git add -f pathToTheFileToAdd

you have to add the following files:

  • Gemfile
  • Gemfile.lock (if here)
  • fastlane/Appfile
  • fastlane/Fastfile
  • fastlane/Matchfile

Gitlab-runner - register your mac

To automate your build with gitlab, you need to setup your mac as a gitlab runner.

sudo curl --output /usr/local/bin/gitlab-runner

Give permission to execute :

sudo chmod +x /usr/local/bin/gitlab-runner

Go to your project gitlab page, then go to settings -> CI/CD -> Runners -> Specitic Runners -> Set up a specific Runner manually -> take note of the token

Follow these instructions to register your mac as a gitlab-runner for your specific project.
Follow macOS instructions without sudo command for registration.

  • Tags: set mac,ios
  • Executor: set shell

Then, to install/launch the runner:

cd ~
gitlab-runner install
gitlab-runner start

Runner is installed and will be run after a system reboot.

Now, you can uncomment the job build-and-deploy-ios in .gitlab-ci.yml to make the app build and deployement work.