iOS App automation with fastlane

Image for post
Image for post

This is the first article of a series on how to automate iOS development and build a continuous deployment pipeline to Apple’s App Store Connect by using fastlane and GitHub actions. The goal is to combine these two tools and create a pipeline to automatically test, build and submit new versions, all done in the cloud.

Why do we want to automate our iOS app development?

Distributing a new app version can cause quite a headache. Often many individual steps have to be performed. Especially when multiple developers are working on an app at the same time, consistent processes are necessary.
App automation helps you to save time, reduce complexity and achieve a more reliable and consistent development process. And it’s a first step towards automated continuous deployment.

I will explain how to setup fastlane. A framework that helps you to automate nearby every aspect of your development. This article is more like a tutorial. We will automate, combine and simplify common development steps like code signing, testing, building and app store deployment.
It’s all done on your local machine and a foundation for a series of articles with a common goal: automated continuous deployment in the cloud.

fastlane

fastlane is an app automation framework that helps you to easily build and release mobile apps by automating nearby all tasks. You can write powerful lanes that contain workflow steps you would normally do by hand one after the other. You can also control more advanced steps like certificate handling or automated creation of AppStore screenshots for multiple localizations.

fastlane also supports Android projects. This makes it viable for native and React Native projects.

Install fastlane

fastlane can be installed on multiple ways. I prefer to install it via Ruby Gems. To keep track of your Ruby dependencies I recommend to create a file called Gemfile in your project root folder.

Put this configuration into your Gemfile:

Image for post
Image for post
https://gist.github.com/thecael/a62335c744aa09deaf87f4461452dcf2

Now you just have to execute bundle install to install all dependencies in the Gemfile. This also installs xcode-install which is quite handy when you have multiple Xcode versions on your system (i.e. the AppStore and the beta version).

If you don’t want to use Ruby Gems you can also install fastlane via brew:

Image for post
Image for post

Setup an example project

This article shows the possibilities of fastlane using a fresh example app. For this purpose let’s quickly create a simple app project in Xcode.

Image for post
Image for post

Since fastlane swift is still in beta I recommend to install the “classic” version with Ruby-style configuration files by executing the fastlane init command in your projects folder. Choose manual installation on the installation prompt. The setup process creates all necessary structure in a subfolder called fastlane.

Unified Certificate handling

fastlane also offers certificate handling for your apps. This is essential if you have multiple developers working on your app at the same time. It will keep your certificate setup clean and you do not have to share certificates between developer machines. match managed the certificates in an encrypted storage. Currently git repositories, Google Cloud storage and Amazon S3 are supported. In this article I use a private git repository on GitHub. So I just created an empty private repository there.

To switch certificate handling to fastlane match simply execute the following command in your projects folder:

Image for post
Image for post

match will ask you for your storage type. For this tutorial it’s git. Now enter the url of our private GitHub repository that you have created. match asks you to enter a strong passphrase for the certificate encryption.

Image for post
Image for post

The next step is to generate certificates that will be managed by fastlane match. If you plan to apply this tutorial to an existing app, please note that this step might nuke your existing certificates. If you want to use your existing certificates at all costs (i.e. you have enterprise inhouse apps) please read this awesome blog post:

Use Fastlane for iOS without messing with your Enterprise certificates | Bartosz Dolewski

Match generates the certificates for us by running the following commands.

You may have to enter your iTunes Connect credentials multiple times.

Image for post
Image for post

This will create development and app-store certificates at the Apple Developer Portal. You can double check it on the web frontend:

Image for post
Image for post

Since match manages all certificates for the project, automatic code signing in Xcode must be disabled for the project.

Image for post
Image for post

Note:
In some cases, you may need to close and reopen Xcode once after running match in order for the new certificates to be properly recognized.

Configuring the lanes

An automation workflow in fastlane is called a lane. In this tutorial we will create lanes for code signing, tests, build and upload. You can execute these lanes with a simple command.

Open Fastfile in the fastlane subfolder and replace the content with this configuration:

The first lines help you to always update to the latest fastlane version and switch to the correct Xcode version.
xcversion(version: “~> 12”) specifies that the fastlane uses latest available Xcode 12 version installed on the host. This is quite handy because we don’t want to update the configuration file on every minor Xcode update. And it allows us to have multiple versions of Xcode installed on the system.
But it’s up you to delete that line and always uses the default Xcode version of the system.

The second part of the configuration describes the actual lanes:

This lane helps you to establish a unified code signing. It installs all required certificates on the machine. The readonly parameter prevents match from overriding the existing certificates.
This is helpful if you run the project on a new development machine or a new developer joins the team.

The tests lane only consists of the scan() command. This command runs all available tests (unit tests and UI tests) in your project.

I tend to split build and upload into two lanes because sometimes you just want to check if your project builds 😀
The goal is to create a binary file that can be uploaded in the upload lane.

This lane uploads the binary produced by the build lane.
You can also put both commands in one lane by moving the build() command to this lane.
Normally, fastlane waits until AppStore Connect confirms the entire upload process. This may take very long. AppStore Connect also sends an email when the automatic processing is complete. You can skip the waiting process by adding the skip_waiting_for_build_processing: true as a parameter.

This is a very simple fastlane configuration file. I’ll write an advanced blog post about advanced configurations (like upload of screenshots, beta testing, beta badges and registering of new test devices) in the future.

Test your fastlane setup

You can test your setup on your machine by running fastlane in your projects root folder. fastlane should greet you with a nice overview and a selection prompt for the lane you want to execute. Run your tests or start a fresh build.

Image for post
Image for post

Please note:
If you adapt this to an existing project and have a complex app scheme setup with multiple schemes and sub-targets it’s helpful to add the scheme parameter to the build() and upload_to_app_store() commands. More information and deep dive explanation of the parameters are here: http://docs.fastlane.tools/actions/build_app/#build_app

Distributing a new app version can cause quite a headache. Often many individual steps have to be performed. Especially when multiple developers are working on an app at the same time, consistent processes are necessary.

App automation helps you to save time, reduce complexity and achieve a more reliable and consistent development process. And it’s a first step towards automated continuous deployment.

fin

In this tutorial we created automated iOS development workflows and set up a unified certificate management for more reliability and consistency. This greatly simplifies the deployment to AppStore Connect in particular especially across a development team.

It’s a first step towards an automated continuous deployment. And it’s a foundation for the next article: “Continues app deployment with fastlane and GitHub Actions”. Stay tuned!

Written by

I’m a Software Engineer from Düsseldorf. Passionate about programming languages & technologies with vocation for agile topics.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store