Set up a Gymfile

Build Automation relies on Fastlane for building Xcode projects. This document describes how to modify the behavior of Fastlane using the Fastlane file format known as a Gymfile. All of the configuration options are very specific to Fastlane, so some basic familiarity with the toolset is recommended.

This section uses a basic example of how you might configure your project to build with multiple profiles currently. The following example assumes you are building an app with an application identifier of "com.unity3d.buildautomation.base" and a stickers extension with an app identifier of "com.unity3d.buildautomation.base.stickers".

Add required files

This setup currently requires adding three extra files to your repository:

File #1: A JSON options file that controls the paths to your custom Fastfile/Gymfile and which lanes in the Fastfile should be run.

This file can be placed anywhere in the repository but is placed at Assets/ucb_xcode_fastlane.json in this example. Supports the following properties (all of which are optional, if you do not use a property remove it entirely): fastfile - a path to your custom Fastfile, relative to the root of your repository. gymfile - a path to your custom Gymfile, relative to the root of your repository. lanes - lanes within the Fastfile referenced above. pre_build - lane to run before the actual Xcode build steps. post_build - lane to run after the actual Xcode build steps.

These paths are all relative to the root of the project.

Example "Assets/ucb_xcode_fastlane.json":

(JavaScript)

{
    "fastfile": "Assets/ucb/Fastfile",
    "gymfile": "Assets/ucb/Gymfile",
    "lanes": {
        "pre_build": "use_stickers_profile",
        "post_build": ""
    }
}

File #2: A custom Fastfile to install the provisioning profile and update the provisioning settings in the Xcode project.

This file can be placed anywhere in the repository, but it needs to match the path of the “fastfile” specified in ucb_xcode_fastlane.json above.

If you’ve configured pre_build/post_build lanes, an options hash is passed to those lanes when they run containing: project_dir - root of the repo this project is building from. build_target - build target identifier for this build. output_directory - final output directory where the Xcode project will build to.

In this example, we are installing the provisioning profile at “Assets/ucb/Stickers.mobileprovision” in the repo, and updating the “Unity-iPhone-Stickers” target in the Xcode project to use that profile.

Example Assets/ucb/Fastfile:

(Ruby)

lane :use_stickers_profile do |options|
    profile_path = File.join(options[:project_dir], 'Assets/ucb/Stickers.mobileprovision')
    FastlaneCore::ProvisioningProfile.install(profile_path)
    update_project_provisioning(
        xcodeproj: 'Unity-iPhone.xcodeproj',
        target_filter: 'Unity-iPhone-Stickers',
        profile: profile_path
    )
end

File #3: A custom Gymfile to define the application identifier to provisioning profile mapping as part of customizing the export options.

This file can be placed wherever you want in the repo, but it needs to match the path of the “gymfile” in ucb_xcode_fastlane.json above. For available options, see the fastlane docs.

In this example, the “com.unity3d.buildautomation.base.stickers” application identifier should map to a UUID of 1e33640e-9a55-4357-a632-ca6c48a53a96 (which is the UUID of the provisioning profile at Assets/ucb/Stickers.mobileprovision).

Example Assets/ucb/Gymfile:

(Ruby)

export_options(
    provisioningProfiles: {
        "com.unity3d.buildautomation.base.stickers" => "1e33640e-9a55-4357-a632-ca6c48a53a96"
    }
)

Update Advanced Settings

All that’s left is to update the Advanced Settings for your build target in the dashboard.

  1. Navigate to the Unity Cloud Dashboard
  2. Select DevOps > Build Automation > Configurations.
  3. Navigate to the iOS build target.
  4. Click Edit.
  5. Navigate to the Edit Advanced Options tab.
  6. Under the Platform specific settings (iOS) option, set the Custom Fastlane Configuration Path, which is the path relative to the project’s root. In this example, it is set as “Assets/ucb_xcode_fastlane.json”.