So you’ve been working on your project for months, weathering countless test failures and bug fixes in the process, and now your app is ready for release. Submitting to the Apple App Store or Google Play Store is supposed to be the easy part, right?
Unfortunately, it’s not always as straightforward as you’d think. You have to build the correct binaries for each store, manage provisioning profiles and distribution certs and sign the binaries properly, sort out dozens of screenshots (maybe hundreds if your app is multilingual), and update your app’s metadata. It’s the kind of menial, repetitive work that quickly wastes time and is prone to errors.
This is where tools like fastlane really shine. fastlane is a mobile release automation tool that helps you streamline tasks like testing, building, signing, and deploying your application to the Apple and Google app stores. fastlane actions are the scripts you can run to automate processes, and lanes allow you to create defined workflows tailored to your specific needs.
In this overview, we’ll share some of the most widely used fastlane actions that can help you build, sign, release, and push assets automatically. We’ll mostly focus on the highlights here, but if you’d like to see a step-by-step tutorial for using fastlane to automate your iOS app release, check out this detailed tutorial.
Don’t have a CI/CD pipeline for your mobile app yet? Struggling with a flaky one?Try Runway Quickstart CI/CD to quickly autogenerate an end-to-end workflow for major CI/CD providers.
We'll share our perspectives on the mobile landscape, peeks into how other mobile teams and developers get things done, technical guides to optimizing your app for performance, and more. (See a recent issue here)
Something went wrong. The App Store Connect API is very powerful, but it can quickly become a time sink.Runway offers a lot of the functionality you might be looking for — and more — out‑of‑the‑box and maintenance‑free.
gym - also known as build_app (there are lots of aliases in fastlane!) - is a fastlane action that helps you build and package your iOS applications by automating beta and production releases. It’s primarily used to build and sign your app and generates a signed .ipa file as output.
To start a build with gym, run:
When you build your app in fastlane by calling the gym action, some default parameters are included, but you’ll need to add additional parameters as your workflow becomes more complex.
For example, the following runs gym with bitcode and symbols included in the .ipa file:
Manually specifying these additional parameters every time you use the gym action can be tedious. By using a Gymfile to define defaults, you can avoid manually inputting each parameter every time you run gym.
The code below creates a new Gymfile:
If you want a little more control over your build process, edit the parameters in your default Gymfile accordingly. A new, empty Gymfile should look like this:
gym makes it easy to split your apps into test and production versions and upload each version to App Store Connect as appropriate. By putting the gym action in a fastlane lane, you can specify the build parameters used in each environment:
On the Android side, the gradle action leverages your existing Gradle build to handle building of your app.
Apple recommends that every development machine has a unique identity for signing code. This proliferation of signing identities becomes a challenge for large teams when everyone needs to download the newest provisioning profiles whenever a certificate expires or a new developer joins.
fastlane has an action called match that elegantly solves this pain point by creating a single identity that can be shared across your entire team. It encrypts and stores your keys and certificates in a private git repository. By setting permissions (e.g., read-and-write or read-only) and enabling two-factor authentication, you can safely ensure that only the team members you authorize will have access.
Let’s look at how to get started with match and some of the key features it offers.
The command below will initialize match:
match gives you the option of storing your keys and profiles with a cloud hosting provider (like Google Cloud or AWS) or a private git repository (like GitHub or Bitbucket). After you’ve selected your preferred storage option, fastlane will create a new Matchfile in the fastlane folder. This file ensures that your configuration options are committed to version control and shared with the rest of your team.
After you’ve initialized match, you must generate or download your team’s certificate and provisioning profiles by running the following commands:
# Generate a distribution certificate and provisioning file for app store use
bundle exec fastlane match appstore
The nice thing is that, once configured with your storage provider, match will automatically get, renew, or create the required profiles and certificates as needed. You can even run this command in your CI tool, although it’s recommended that you add the --readonly flag:
If you stop working on an app for a while and the certificate lapses, you won’t be able to auto-renew it, but you can remove and regenerate it manually. If using git, this process should look something like this:
# Generate the profile and certificate again
bundle exec fastlane match development
Uploading your app to TestFlight is another task that’s great to automate with fastlane. Each time you make an update, Testflight requires you to manually log in to the Apple Developer Portal, generate a provisioning profile, log into App Store Connect, and re-create your app. Then, you have to add a description and keywords for your app, take screenshots, and upload the relevant builds to initiate TestFlight.
With fastlane, the upload part of this process can be automated with the pilot action (an alias for upload_to_testflight). pilot commands require either an API key or your Apple ID, but once authenticated, fastlane will do the hard work of uploading your app and assets to TestFlight.
Assuming you’ve already built your .ipa file manually or with gym as described above, you can run pilot with the following command:
This action will upload the .ipa file in your project directory and use the login credentials from your fastlane configuration.
There are several flags you can include in the pilot action. For example, you can specify the filepath to the .ipa file with --ipa or include “what to test” text with the --changelog flag. To debug errors encountered during the upload process with pilot, you can use the --verbose flag:
You can even use fastlane pilot to manage internal and external testers for your app. This allows you to dynamically swap out test users and groups as a function of the type of beta you’re releasing. For example, you might only want internal testers to get early beta releases, saving your external testers for more polished versions of the app.
To bring it all together, let’s talk about pushing assets to the Apple App Store. fastlane deliver is an action that allows you to automatically upload localized screenshots, binary .ipa files, and metadata to the App Store. By integrating this action with your continuous integration and delivery pipeline, you can make releases quite hands-off for your team.
deliver stores your release configuration files in git, making them available to any developer, so you no longer need to have a single person in charge of every release. Additionally, it provides an HTML preview of the metadata you’re about to send to the App Store, allowing your team to check the final product before you ship it.
To create your first fastlane deliver action, enter the following:
This will prompt you to log in to App Store Connect if you haven’t already done so in your fastlane project. It will also ask you to enter your bundle identifier to ensure you have the necessary permissions. Finally, deliver will download the current version of your app’s metadata and screenshots.
To upload your binary file and submit your updated app for review, run the following:
There are many other options you can pass into the deliver action, including language codes, custom paths for your metadata and screenshots, and your app’s categories. Like all the actions outlined here, you can also add deliver’s flags to your Fastfile so they’re checked into version control and automatically applied:
fastlane supply is the Google Play Console equivalent of fastlane deliver. Like deliver, supply allows you to automate the app store submission and update process and run everything via your command line or CI/CD tool of choice. supply ships new .apk files or .aab bundles, updates metadata, uploads your application icon, graphics, and screenshots, and incrementally updates the app version number.
Most of supply’s features are similar to deliver’s, so if you read the section above, you should be in familiar territory. To initialize supply and download the existing metadata, run the following:
You may have a description, title, and/or video clips as part of your app’s metadata folder:
Assuming you’ve already built your Android App Bundle, you can run the following command to push your updates to the Play Console:
Of course, if you’re still building apk binaries, fastlane supply supports them as well:
You can release your update to a specific track (production, beta, alpha, internal) by adding the --track flag. Similarly, you can promote a test version of your app to production after users have tried it out using the --track_promote_to flag.
There are many other parameters covered in the docs, and like the options available in deliver, you can specify these in your Fastfile to ensure developers don’t forget them.
fastlane is an extremely capable tool, but it can quickly become a complex and sometimes fragile piece of your toolchain — so it’s a good idea to get comfortable with a few basic actions and build your way towards a more fully automated ideal.
In this piece, we’ve highlighted some of the most helpful and commonly used fastlane actions. Together, they help you handle building, signing, and delivery to the app stores, and they form a solid foundation on which your team can build a more automated and complex mobile CI/CD pipeline.
