Fastlane (iOS)

Fastlane is an industry standard tool for mobile developers that enables the creation of complex continuous integration workflows. Fastlane configurations are varied and unique to their project's needs, so if you need help setting up your Fastlane install we recommend getting started here.

Emerge provides a Fastlane Plugin that helps upload builds of your app to Emerge. While Emerge supports other integration methods such as Xcode Cloud, Code Magic, and a REST API, Fastlane is the recommended method for uploading builds to Emerge. If you haven't yet setup Fastlane and Github Actions you can find integration instructions here.

Install the plugin

The Emerge Fastlane Plugin makes it easy to upload iOS builds in your CI pipeline. You can add it to your project by running:

fastlane add_plugin emerge

Call the upload API

Uploading a binary to Emerge is easy. All you need to do is provide the API key in your Fastfile as an environment variable (ideally without including it in source control, for security), and run the Emerge action like so:

# Your EMERGE_API_TOKEN is available on your Emerge profile page: https://www.emergetools.com/profile
ENV['EMERGE_API_TOKEN'] = 'COPIED_FROM_EMERGETOOLS_PROFILE'

platform :ios do
  lane :app_size do
    emerge()
  end
end

This will upload the provided archive to Emerge for processing and print a URL to view the results.

📘
Fastlane Context
The archive path can be shared from your other lane steps using lane_context. If you're already building the app in Fastlane using build_app (also known as gym) you can omit the file_path parameter and it will automatically be inferred from context.
Otherwise, if you aren't building your project in Fastlane you will need to include a file_path argument like so:
file_path: "/path/to/your/.xcarchive"

Additional Parameters

Calling emerge() with no parameters is supported because the parameters are automatically inferred from the context, but more complex setups may require additional configuration. Some common reasons to provide additional parameters include using platforms such as Gitlab or Bitbucket, or integrating tools like merge queues which change the your commit's SHA.

The parameters below work with the Emerge GitHub app to find the base build that was already uploaded and post the comment to your PR.

base_sha: The SHA of the base commit your app was built from. For example, the last commit from main before you created the current branch.
branch: The name of your current git branch.
file_path: The path to your xcarchive. If you are building the app in Fastlane using build_app (also known as gym) you can omit the file_path parameter and it will automatically be inferred from the context.
pr_number: Number of the pull request that triggered this build.
repo_name: Name of your GitHub repository.
sha: The SHA of the commit that your app was built from.
tag: You can use this to filter builds in Emerge's dashboard, teams most commonly use this to separate development builds from release builds. If no tag is provided the default will be set to development.
release_notes: A markdown string displayed when users install the app.
app_id_suffix: An optional string that when included will be concatenated to the end of the app's identifier. This will allow you to fully differentiate between uploads of the same id depending on different configuration, such as the archive build configuration (ex. debug vs release). More info

A more customized emerge() function call would look like this:

emerge(
  file_path: "/path/to/your/.xcarchive",
  repo_name: "EmergeTools/MyAwesomeApp",
  pr_number: "42",
  sha: "Full git SHA",
  base_sha: "Full git SHA",
  previous_sha: "Full git SHA",
  tag: "release"
)

Sample Project

We have a sample project that is kept up to date and provides a good example of how to set up an Emerge-integrated project. It's particularly helpful if you need a reference to a valid iOS Github Actions Workflow or if you need to reference a working Fastfile.

👍
Congrats on integrating Fastlane with Emerge!
Please feel free to contact support with any issues or feedback!