fastlane Tutorial: Actions and Plugins

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.

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:

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:

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.

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:

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:

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!