Cyber Monday Sale — Save on Everything.All videos. All books. Now 50% off.

Ends in... ::
Home iOS & Swift Tutorials

fastlane Tutorial: Actions and Plugins

In this fastlane tutorial, you’ll use actions and plugins to overlay your app icon, upload to Firebase and message your team once the beta build is ready.

5/5 3 Ratings


  • Swift 5, iOS 14, Xcode 12

fastlane is a tool that automates your development and release process, saving you time, eliminating repetitive tasks and minimizing human error. In fastlane Tutorial: Getting Started, you learned how set up, build, test, archive and upload your app to TestFlight entirely using fastlane.

This tutorial builds on those skills so it’s a good idea to complete that tutorial before continuing. Here, you’ll learn how to use other actions and plugins to add an overlay to your app icon for beta versions, upload to Firebase for testers and send a message to your team on Slack once the build is ready.

Note: This tutorial assumes that you have a paid Apple Developer account and basic knowledge of the command line, Xcode and the ad-hoc testing process. If you don’t have an account, our tutorial, How to Submit an App to the Apple Store, will help you.

Getting Started

Start by using the Download Materials button at the top or bottom of this page to grab a copy of the sample project. Once you’ve downloaded the materials, extract the .zip archive somewhere convenient on your machine.

As in the first tutorial, you’ll work on a sample app called mZone Poker, which is a calculator for no-limit Texas Hold ‘Em tournaments. It works by displaying a recommended action based on the chip count and the current big blind level that you enter.

Build and run to check it out:

mZone Poker App

Before you start working on the app, however, take a minute to set everything up properly.

fastlane Configuration

You should already have fastlane and Bundler set up from the previous tutorial, so open Terminal, navigate to the starter project directory and run the following command:

bundle install

This command asks Bundler to install all the dependencies defined in your Gemfile so you’re ready to execute the rest of the commands in this tutorial.

Signing Assets Configuration

You need to set up your signing identity and bundle ID in Xcode before getting started. These values are your unique team ID from your Apple Developer account and a unique app bundle identifier you created in the Identifiers section of the Apple Developer Portal. If you followed the previous tutorial you should already be set.

After you’ve set up your account, perform the following steps:

  1. Open mZone Poker.xcodeproj from the starter folder in Xcode.
  2. Reveal the Project navigator in Xcode’s left pane.
  3. Select the top mZone Poker project node.
  4. Click the mZone Poker target under the Targets heading.
  5. In the middle pane, select the Signing & Capabilities tab.
  6. Ensure that you’ve selected the Automatically Manage Signing checkbox.
  7. Select your development team in the Team drop-down.
  8. Enter your bundle ID in the Bundle Identifier field.

You can see where to perform each of these steps in the image below:

The Signing & Capabilities tab in Xcode 11

Note: If you don’t see your development team listed in the drop-down, try signing in with your Apple ID. Do this by going to XcodePreferencesAccounts in the menu.

After you’ve followed the steps above, the error “Signing for mZone Poker requires a development team” will disappear and you’re ready to go. Now, it’s time to start improving your mZone Poker app.

Adding an Overlay to the App Icon

What if your beta testers could differentiate your beta builds on the device by glancing at the app icon? fastlane makes this easy!

In this step, you’ll set up a lane to update your app icon for beta builds. The updated icon will include custom text that allows you to easily see information about the beta build on your device.

App Icon with overlay applied

Before you start, however, take a quick detour to understand fastlane plugins.

fastlane Plugins

fastlane publishes a default set of actions with the default install. They’re available from your lanes without any additional work. The default actions are often for first-party tools, such as Xcode or Android Studio, but there are many other actions available that provide integration for third-party tools or non-essential utilities.

These additional actions are available as plugins, which you can install alongside the default fastlane installation. Once you install them, you can use them in your Fastfile as easily as the default actions.

You can find out more about how plugins work by reading the official documentation. You can view a complete list of published plugins in the fastlane docs.

Icon Versioning Prerequisites

Before you start configuring fastlane to add an overlay to your app icon, you need to take care of some housekeeping. The fastlane plugin you will use to overlay the icon requires the ImageMagick command-line utility to do its work. You will use the Homebrew package manager to install it.

If you don’t already have Homebrew installed, go to the site and copy and paste the installation script on the homepage into a Terminal session. Run the command and follow the on-screen instructions to complete the setup.

After that, install ImageMagick with the following command:

brew install ImageMagick

After ImageMagick and all its dependencies install, you’re ready to set up your first fastlane plugin!

Installing the Icon Versioning Plugin

To use a plugin, you have to perform a few extra steps to install it and make it available to fastlane. You’ll use the Icon Versioning plugin today to update the app icon.

To start, open Terminal and run the following command:

bundle exec fastlane add_plugin fastlane-plugin-icon_versioning

Since this is the first time you’re adding a plugin to this project, you’ll see some output like the following:

Prompt fastlane presents when adding a Pluginfile

This tells you a few important things:

  1. You successfully added the plugin to your Pluginfile.
  2. Since you haven’t used plugins before, fastlane needs to modify your Gemfile to reference your plugins. This is a one-time prompt that fastlane shows just because it wants to make sure that it has your permission to modify a file that it didn’t create. This file was one of the materials you downloaded.

Press y and the process will continue:

fastlane plugin install success message

Note: If you see a message saying Seems like this plugin is not available on RubyGems, select option 3. This will attempt to install the plugin from RubyGems.

Open ./fastlane/Pluginfile. Its contents will look like this:

# Autogenerated by fastlane
# Ensure this file is checked in to source control!

gem 'fastlane-plugin-icon_versioning'

This file is auto-generated; you don’t have to edit it. It’s basically a Gemfile that lists gems — aka plugins — you added specifically for fastlane.

Since fastlane adds a reference to this file in your existing Gemfile, whenever you run bundle install again, the plugin will also be installed for you (if it wasn’t already).

This is useful when using source control and working with other team members or for when you’re relying on build servers where you’ll also need to install your plugins.

Now, it’s time to set up your app icon overlay!

Creating a Lane for Icon Overlay

Open a plain text editor like Atom or Visual Studio Code. From the base directory of the starter project, open ./fastlane/Fastfile and add the following code underneath platform :ios do:

desc "Overlay the app icon with build information"
lane :overlay_icon do
  # 1
  build_number = get_build_number
  # 2
  version_number = get_version_number
  # 3
    appiconset_path: "mZone Poker/Assets.xcassets/AppIcon.appiconset",
    text: "beta: #{version_number} (#{build_number})"

This code does the following:

  1. Uses the built-in get_build_number action to retrieve the current build number.
  2. Uses the built-in get_version_number action to get the current app marketing version.
  3. Calls the version_icon plugin’s version_icon action to update the app icon with an overlay that shows the app version and build number across the bottom.

Now, open Terminal and run the following command:

bundle exec fastlane overlay_icon

You’ll see some terminal output and a success message. After the script finishes, take the following steps to validate the changes and create the overlay:

  1. Go to the project directory in Finder.
  2. Navigate to the following path: mZone Poker ▸ Assets.xcassets ▸ AppIcon-Versioned.appiconset. This is a copy of the original icon set. The Icon Versioning plugin created this icon set as a duplicate of the original and created the overlay for the beta icons here.
  3. Select one of the files and preview it.

You’ll now see an overlay on the icon containing the marketing version and build number:

App Icon with overlay applied

Now that you’ve generated a new App Icon for your beta build, it’s time to generate the build itself using fastlane’s gym action.

Creating a Build

fastlane comes with an official library of actions. They ship with fastlane and you can call them from any lane. To view the full list of available actions, check out fastlane’s actions documentation. Gym is one of those commands.

Setting up Gym to Build

You need to generate a binary so you can perform an upload for beta testers. You’ll use the gym command to generate an .ipa file for this.

Open fastlane/Fastfile in your text editor and create a new lane underneath overlay_icon with the following code:

desc "Build beta ipa"
lane :build_beta do
  # 1
  # 2
    export_method: "ad-hoc",
    # 3

This lane:

  1. Turns on automatic code signing, which means you don’t have to fuss with provisioning profiles and other code-signing settings.
  2. Runs the gym command and sends ad-hoc through for the export_method parameter value. This builds the app for testing. Any devices attached to your Apple Developer account on the portal can run the app.
  3. Overrides the ASSETCATALOG_COMPILER_APPICON_NAME build setting to force the build into using the previously-generated AppIcon-Versioned asset instead of the default app icon selected in Xcode. This is a great way to ensure that you only apply your beta icon when making beta builds.

Save the Fastfile and run your new lane with the following command:

bundle exec fastlane build_beta

If this is your first time running the gym command from fastlane, you might get a codesign prompt like the following:

Codesign Prompt

If so, enter your administrator password and select Always Allow to continue. Once fastlane has finished building your app, you’ll get a success message. Just above that, you’ll see where on the file system it saved your build.

Navigate Finder into the ./fastlane/builds/ directory and you’ll see mZone Poker.ipa waiting for you to upload it. :]

Finder displaying the .ipa file output by fastlane

Uploading to Firebase

Your next step is to make your builds available to testers. There are several platforms that allow uploading ad-hoc builds for testing. In this case, you’ll use Firebase.

Before getting started with Firebase, you’ll need to set up an account and install the local command line interface (CLI).

Setting up a Firebase Account

If you don’t have a Firebase account already, go to Firebase and set one up. This gives you access to Firebase App Distribution, which is the tool you’ll use to distribute beta builds.

Once your account is active, the next step is to install the Firebase CLI.

Note: Many Firebase features require you to embed the Firebase framework into your app, but App Distribution isn’t one of them. You don’t need to use the Firebase SDK to distribute beta builds.

Setting up the Firebase CLI

Go to the Firebase CLI installation page and follow the directions to set it up. After configuring the CLI, follow the instructions to log in and run the recommended test.

Setting up Your Project on Firebase

After you set up the tools, it’s time to create a project and app on Firebase.

A project is a logical container for one or more apps. You can have multiple apps under one project and they can all share settings, testers and other Firebase values.

Follow these steps to create your project:

  1. Go to the Firebase console.
  2. Click the Add project option.
  3. Give your project a name.
  4. Choose whether to enable Google Analytics or not — you don’t need to for this tutorial.
  5. Continue through the remaining screens until Firebase redirects you to the Project Overview for your newly-created project.

Now that you’ve set up your Firebase project, it’s time to add an app within your new project.

Setting up Your App on Firebase

On the Project Overview page, you’ll see a prompt to add Firebase to your app. Select the rounded iOS button to start configuring your app:

The first-time prompt from Firebase to add an app within your Project

Set up your new app by typing the bundle identifier that you used earlier in Xcode into the iOS bundle ID field. Leave the other two fields blank and click Register app.

Configuration screen for adding an iOS app in a Firebase project

Select Next for the next three steps since you don’t need to configure the Firebase SDK within this app. Once you reach step 5, click Continue to console to return to the Project Overview. You’ll see your app displayed at the top of the page:

Screenshot of Firebase App in Project Overview

Next, you’ll set up App Distribution for the mZone Poker app.

Setting up App Distribution

To set up App Distribution for your newly-created app, head to the dashboard by clicking the App Distribution item in the menu on the left of the screen:

Firebase Console side menu with an arrow pointing to the 'App Distribution' option

The first time you visit, Firebase will present you with resources to help you learn more about the feature. In this case, you can just click Get Started to jump right in.

From this screen, go to the Testers & Groups tab and click Add Group. From there, name your new group beta-testers and click Save.

App Distribution console for adding a new group

Here, you’ll see a button to Add testers. Click it, type your own email address and press Enter to add yourself as a tester:

Screenshot of confirmation after adding a tester

Now, you can test any builds you upload to Firebase. Before you start uploading, however, there’s one more thing you’ll need from the Firebase Console: your Firebase App ID.

Finding your Firebase App ID

You need to tell Firebase where to upload your apps. To do that, you have to use the unique identifier of the app you created earlier.

To find this value in the Firebase Console, click the settings cog in the left-side menu and select the Project Settings option:

Firebase Console menu

From the General tab, scroll down to the Your apps section and look for the value under App ID.

Take note of the ID. You’re now ready to start integrating the plugin.

Setting up the Firebase App Distribution Plugin

Next, you need to set up the Firebase App Distribution plugin. This tool allows you to upload to Firebase from fastlane with an action.

From Terminal, run the following command to add the App Distribution plugin to your fastlane installation:

bundle exec fastlane add_plugin firebase_app_distribution

Console output after adding Firebase Plugin

Now that you’ve installed the plugin, you’ll create your next lane.

Creating an Upload Lane

Open your Fastfile and add the following lane, being sure to replace [[FIREBASE APP ID]] with the App ID you noted when setting up the Firebase project:

desc "Upload to Firebase"
lane :upload_firebase do
  # 1
    # 2
    ipa_path: "./fastlane/builds/mZone Poker.ipa",
    # 3
    app: "[[FIREBASE APP ID]]",
    groups: "beta-testers",
    # 4
    release_notes: "Added icon overlay and started distributing via Firebase"

This is what the code above does:

  1. Invokes the firebase_app_distribution action provided by the newly-added plugin.
  2. Tells the action where on your machine it can find the .ipa you want to upload.
  3. Specifies the app to upload to and the group of testers that should have access to it.
  4. Provides release notes so your beta testers know what’s new in this build. For now, you’re just hard-coding a string to keep it simple. If you’re using Git, however, you can combine other actions such as changelog_from_git_commits to automatically populate the release notes for you.

After all that setup, you’re probably looking forward to testing this, so run the following command from Terminal:

bundle exec fastlane upload_firebase

A few minutes after the lane completes, you’ll get an invitation by email to test your beta from Firebase. Great job! You now have a way to generate a beta inside a repeatable build script.

For your final step, you’ll learn how to send a message to a Slack group when a build is available.

Messaging Your Team on Slack

For this step, you need to have a Slack account with access to a workspace.

You then need to add an Incoming WebHook that allows Firebase to post incoming messages to Slack. To do this, visit the Incoming WebHook app in the Slack App Directory and click Add to Slack. You’ll then see the configuration page:

Slack App page for configuring WebHooks

On this page, select an existing channel from the Choose a channel… drop-down or click create a new channel and follow the steps. Once you’ve selected your desired channel, click Add Incoming WebHooks Integration and you’ll get a Webhook URL:

Screenshot of a new WebHook

Go back to the Fastfile and add another new lane by entering the following code under the last lane you added:

desc "Send Slack notification for build"
lane :send_slack do 
  # 1
  build_number = get_build_number

  # 2
  version_number = get_version_number

  # 3
    message: "App build complete for Version: #{version_number} (#{build_number})",
    success: true,
    payload: {
      "Build Date" =>,
      "Built by" => 'fastlane'
    slack_url: "[[SLACK INCOMING WEBHOOK URL]]"

Don’t forget to replace [[SLACK INCOMING WEBHOOK URL]] with the Webhook URL you obtained.

This lane does the following:

  1. Uses the built-in get_build_number action to retrieve the current build number.
  2. Uses the built-in get_version_number action to get the current app marketing version.
  3. Runs the slack action to post a message to your Slack workspace with a build notification.

    The action receives the following values:

    • message: The message to post, which uses the build number and marketing versions from step one and two.
    • success: A Boolean indicating build success.
    • payload: Additional message data to pass along. Must contain a hash of keys and values. In this case, you’re passing the build time and a Built by attribute.
    • slack_url: your incoming webhook URL.

Test your new lane by running the following command from Terminal:

bundle exec fastlane send_slack

You’ll get a notification in your #test channel in Slack:

Message posted into Slack channel

There are a ton of customization options available with this action. If you’d like to learn about the full range of parameters available for the slack action, check out the fastlane documentation.

Putting It All Together

Now, you can combine your new actions into one lane. Under send_slack, add the following:

desc "Create and distribute a beta build"
lane :beta do

The only thing that’s new here is increment_build_number. This built-in action takes the existing build number, increments it by one and saves it in your Info.plist under the CFBundleVersion key.

A unique build number identifies each binary submitted to the App Store and any testing services you use. The rest of this lane strings together the actions you’ve built in this tutorial.

To test your complete implementation, run the following in Terminal:

bundle exec fastlane beta

Where to Go From Here?

Download the final project by clicking the Download Materials button at the top or bottom of this tutorial.

In this tutorial, you learned how to prepare and build a binary for beta testing, update the app icon to show build information, upload a test build to Firebase and send a notification message to your team via Slack when it’s ready.

There are many more actions available via fastlane and through fastlane plugins. To take your fastlane skills even further, review all the available actions and plugins and try some other ones out!

If you don’t find something that meets your needs, consider building your own and contributing it to the community.

For further in-depth tutorials, check out our course, fastlane for iOS. There are also screencasts on Submitting Your App With fastlane, Taking Screenshots and App Provisioning.

We hope you enjoyed this tutorial. If you have any questions or comments, please join the forum discussion below!

Average Rating


Add a rating for this content

3 ratings

More like this