iOS developers have been fortunate enough to enjoy and work with the robust development platform that Apple has provided, primarily Xcode. This has helped inspire the engaging and powerful apps that consumers enjoy on the App Store today. Xcode provides an intuitive IDE and that, coupled with the emergence of Swift as a truly modern programming language, has made programming on the platform sheer enjoyment.
However, while the development aspect of the workflow is cohesive, the workflow breaks down when it comes to the chores involved in dealing with code signing and distributing apps. This has been a long-standing problem for the platform, and while it has improved incrementally, it is still a bottleneck for almost all developers. This has in many respects stifled continuous delivery of apps—that is to say, the need for manual building and distribution of apps daily internally and externally is error-prone and laborious.
That's where fastlane comes in. The fastlane suite of tools makes distributing apps much easier, allowing developers to focus on their apps and let the tooling take on tasks like managing provisioning profiles and certificates and building, packaging and distributing apps. One of fastlane's toolchains is a client-side automated Continuous Delivery turnkey solution that iOS developers can leverage to ensure their apps get tested and validated continuously by others, with minimal human intervention.
Developed by Felix Krause (@krausefx), fastlane consists of an open-source suite of tools that unifies the automation of building and deploying iOS apps via the command line, as well as integrating with various third-party libraries in addition to Apple’s own APIs. As somewhat of a cult toolchain amongst iOS developers, and backed by Google, fastlane will save you lots of time by automating a lot of your manual daily and weekly tasks.
In this tutorial, we are going to explore two very popular features of fastlane: code signing and packaging/distributing apps.
Objectives of This Tutorial
This tutorial will introduce you to the fastlane toolchain and show you how to leverage the tool to automate and optimize your iOS development workflow. You will learn:
- the basics of getting started with fastlane
- code signing your app
- packaging and distributing your app
This tutorial assumes you have a working knowledge of Swift and iOS development, although you won't be doing any Swift coding in this tutorial. You'll be using the command prompt to build and run fastlane commands.
Getting Started With fastlane
The fastlane toolchain is essentially written in Ruby and connects to the Apple Developer Center and iTunes Connect API via the spaceship Ruby library, authenticating and authorizing users securely. It operates around the creation of a configuration file, called a Fastfile, which you can think of as a recipe file where you set the actions you want to be performed when building your app. These actions are organized into "lanes". For example, you would configure a lane for deploying to the App Store, and another lane for distributing to TestFlight. A lane could be composed of the following individual actions:
- building your project
- incrementing the build number
- running unit tests
- sending your .ipa to TestFlight
- sending a Slack message to your team
You can think of lanes as functions which group related tasks. You can even call lanes methods from another one, to further decouple and reuse your lanes.
But before we dive into the fastlane actions, you will need to set up your environment to use fastlane.
Setting Up fastlane
Make sure you have the latest version of Xcode installed. You will also need to have Xcode Tools installed on your system. You can check whether Xcode Tools is installed by entering the following in the terminal:
If you get back the full path to your developer folder then you are ready to go. You should see something like the following.
Otherwise, let's get the latest version of the Xcode command line tools by typing the following, in terminal:
You should get a prompt similar to the following:
Next, you are going to need to install Homebrew. Homebrew is a powerful package manager that lets you install hundreds of open-source tools, fastlane among them. To install Homebrew, type the following in the command line:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/
Once Homebrew is set up, you can install fastlane by entering:
brew cask install fastlane
Note that if you prefer not to install Homebrew, you can install fastlane directly in the terminal via ruby, by entering the following:
sudo gem install fastlane -NV
To confirm fastlane is installed and ready on your system, enter the following command in the terminal to initialize a new fastlane configuration file:
You will be prompted to enter your Apple ID so that fastlane can hook into iTunes Connect seamlessly. Fill out any other prompt questions and you will see a new /fastlane sub-directory created for you. You will be primarily concerned with the /fastlane/Fastfile configuration file, where you will orchestrate all of your fastlane actions.
Take a quick look at the file. You will be working with it over the next few sections, starting with configuring fastlane to code sign your apps.
Code Signing Your Apps
One of the most popular features of fastlane as a toolchain is in being able to code sign your apps automatically, avoiding the ordeal of having to deal with certificates and provisioning profiles. This can be a lot of work and, moreover, when you change machines or onboard a new team member, you have to do it all over again. Fastlane provides three actions that help you manage your code signing: cert, sigh, and match.
cert, while useful on its own, usually works in tandem with sigh to complete the process of code signing your app, by managing your certificates and provisioning profiles respectively. It not only creates the certificate for you but will automatically generate a new private key signing request when needed, as well as retrieving and installing the certificate into your keychain, making sure that your certificate is valid each time you run cert.
sigh creates the corresponding provisioning profile for your certificate for either development, Ad Hoc, or the App Store. Like cert, sigh ensures this provisioning profile stays current, retrieved, and installed into your keychain. Together, these two form the code-signing pair for your app. But before you learn how to use cert and sigh, there is one more related action I want to introduce: match.
match combines the two previous actions but allows you to share your code signing identity across your team, or across multiple machines, securely and privately through your own GitHub repository, creating all the necessary certificates and profiles so that new members can get those credentials by simply calling the fastlane command
match. For more information on the concept of match, consult the new approach to code signing guide.
To starting using cert, run the following command:
Similarly, to run sigh:
If you want to see a list of options cert or sigh provides, you can do so with the following commands:
fastlane action cert ... fastlane action sigh
Besides running those commands ad hoc, you can include either or both actions as part of your automated workflow, within the Fastfile configuration file I mentioned earlier:
lane :TestApp do cert # or the alias get_certificates sigh # or the alias get_provisioning_profile end
You can then run the entire lane by issuing the following command:
With two simple lines, you now benefit from having your certificates and provisioning profiles created for you and maintained automatically. Next, you will dive into how fastlane can help package and distribute your apps.
Package & Distribute Your Apps
The next two actions you will learn about are gym and deliver, which you will leverage to build, package, and distribute your app to TestFlight or the App Store. gym builds and packages your app via a single command line, generating a signed ipa file for you.
By automating this as part of your Fastfile, you can trigger building and packaging through a continuous integration workflow and have the latest version of your app in the hands of users daily or hourly. To package your app through fastlane, you can simply run:
To specify a particular workspace and scheme, you can add the following optional parameters:
fastlane gym --workspace "YourApp.xcworkspace" --scheme "AppSchemeName"
Just like Fastfile, fastlane provides a convenient configuration file called a Gymfile where you can store all of your build-specific commands, such as your workspace, schemes and more, saving you having to type that out each time or expose it within your Fastfile configuration file. To create a new Gymfile, simply enter the following:
fastlane gym init
You can then edit that file and enter the configuration parameters necessary for your project.
Next up, deliver takes over where gym left off, by distributing your .ipa file without you having to go through Xcode. As the counterpart to gym, deliver is not only capable of delivering your .ipa binary file but also uploads your screenshots and metadata to iTunes Connect for you, as well as submitting your app to the App Store.
The action can also download your existing screenshots and metadata from iTunes Connect. The simplest action command is to call:
fastlane deliver init
The end result is a metadata and screenshots folder along with the configuration file Deliverfile, which is similar to the Gymfile and Fastfile.
You can then modify the contents of those subfolders to modify your app metadata. To upload your metadata, you run:
To submit your app for review, append the following parameters:
fastlane deliver --ipa "App.ipa" --submit_for_review
To download metadata or screenshots, add the following parameters, respectively:
fastlane deliver download_metadata ... fastlane deliver download_screenshots
You can modify your screenshots within the /screenshots sub-folder, but fastlane provides another action that can automate the process of generating screenshots for you. Although screenshots is outside the scope of this article, you can learn about it in a future fastlane article.
As with the previous set of actions, you can either run gym and deliver on your own or include it as part of your automation workflow, within Fastfile:
lane :TestApp do cert sigh gym(scheme: "AppSchemeName", workspace: "YourApp.xcworkspace") # alias for "build_ios_app" slack end
By enabling continuous delivery through automation, fastlane takes the burden of labor off iOS developers with a one-click turnkey solution for building, packaging, distributing, code signing, screenshot generation and much more. This tutorial just scratches the surface of what's possible with fastlane, and in subsequent articles we will explore more actions you can implement to further automate and optimize your workflow.
From generating localized screenshots to its deep integration with prominent tools such as Jenkins CI, Git, Crashlytics, HockeyApp, and Slack, fastlane is as essential as CocoaPods for your development iOS toolkit. It has a robust community of third-party plugins and is also backed by Google.
You can also learn all about the art of continuous delivery and fastlane in my book Continuous Delivery for Mobile With fastlane, available from Packt Publishing.
And while you're here, check out some of our other posts on iOS app development!