During a typical Android app development cycle, whenever you release or update your app you have to assemble the source code into an APK or App Bundle, which you then deploy to the Google Play Store. On its face, this may seem like a simple process, but a lot goes on behind the scenes: signing the package, updating app metadata, adding screenshots, checking descriptions, and updating changelogs among them. You must repeat this process every time you update your app, so these tasks add up.
The good news is you can automate these tasks, saving your time for new features and bug fixing. All you have to do is use fastlane. fastlane is an open-source set of tools designed to simplify Android and iOS deployment. These tools let you automate your release processes, saving you hours of developer time and reducing errors.
In this tutorial, we’ll learn how to build a local fastlane pipeline that will automate everything required to build and update an Android application so that it’s ready for the Google Play Store. You can find the final source code on GitHub, but as you follow along with this tutorial you’ll learn how to:
If you’re looking for a similar guide for iOS, check out my previous tutorial here.
There are many ways to install fastlane, but for this tutorial, we’ll use Ruby.
You must have Ruby installed on your machine. To confirm that this is the case, open your terminal and run:
If Ruby is not installed, follow the instructions here to add it.
To install fastlane, run the following command in your terminal:
When the installation completes, confirm it by running the following command:
Now you’re ready to use fastlane for your next Android project. Let’s configure some of the basic options you’ll need to get started.
To add fastlane to an existing project, go to your project’s root directory and enter:
Next, enter your app’s unique package name. This package name will be stored in fastlane for future tasks.
The terminal prompt will then ask for the path to your service account JSON file, but we’ll handle that later in the tutorial, so press Enter to skip it for now.
Next, fastlane will ask if you plan on uploading metadata, screenshots, and builds to Google Play. You can either create brand new app metadata and screenshots or download the existing metadata if your app has already been submitted. For now, press n to skip this step, as we’ll set it up later in the tutorial.
When the installation is finished, you will see a new directory called <code>fastlane<code> that contains:
fastlane stores automation configurations in the Fastfile where it groups different actions into lanes. These lanes represent different release processes, and the actions are steps taken within each lane.
A lane starts with <code>lane:name<code> and then includes an optional description in the <code>desc<code> field. Open your Fastfile, and you will see:
As you can see, there are already three lanes inside the file: test, beta, deploy.
In the rest of this tutorial, we’ll see how to fill in details for each of these lanes to build your app, create screenshots, and ultimately submit the app to the Google Play Store for distribution.
fastlane’s Gradle action can run any Gradle-related tasks, including building and testing your Android app. As you’ll see in the following sections, you can configure the Gradle action to suit the type of build you’re trying to run.
When you create a new Android project, you get two build types: <code>debug<code> and <code>release<code>. You can add the appropriate configuration to each build type to add or change specific preferences for each.
To define your build types, add the following to your Fastfile:
This includes options to make sure the debug build stands out (with a suffix), and it ensures the release build is minified, signed, and Proguard rules are applied. Any of the Android build system configuration options found here can be added to your fastlane build options.
Product flavors give you additional options for Android build variants. Add the following to create two product flavors (<code>demo<code> and <code>full<code>) to your app:
Version code determines whether the current build version is more recent than another, so it’s a critical component of your app update and maintenance strategy. You must increase the value of your <code>version code<code> with each release to indicate changes.
If you’re not using fastlane, you have to manually update your <code>version code<code> in your <code>build.gradle<code> file every time you make an update. Versioning is much easier with fastlane; you simply need to add the plugin shown below:
Once the plugin is installed, open your Fastfile and add a lane to increment the <code>version code<code> automatically:
Next, run the lane in your Terminal:
Once the command runs, your <code>version code<code> inside the <code>build.gradle<code> file will be incremented. You can add this lane for every build going forward, thus removing the need to manually update your app’s version number every time you submit a release.
Now that you’ve added build types, flavors, and versioning to your project, you can run them by adding the following to your <code>build<code> lane:
To build the app, run:
fastlane will clean and assemble the app, building only the <code>release<code> build type. App signing will be done according to the declaration in the <code>release<code> closure. Later in this tutorial, we’ll configure a signing key, so you can skip this part for now.
If your app build succeeded, you will see the following message:
With one major task down, let’s take a look at how you can automate your screenshot process in fastlane.
Fastlane uses screengrab to automatically generate localized screenshots of your Android app across dozens of device types. Taking hundreds of screenshots like this manually would take hours, so this could be a huge win for your team.
Before proceeding with the automation, you need to add the following permissions to your src/debug/AndroidManifest.xml:
With the required permissions in place, you can use the instrumentation testing toolchain to set up screenshot automation.
Before you begin, open app/build.gradle and add the following <code>dependencies<code>:
Your project may already have some of these dependencies, so adjust accordingly.
Next, inside the <code>defaultConfig<code> block, add <code>testInstrumentationRunner<code>:
After you sync Gradle, you can move on to configuring your instrumentation tests.
Find or create an instrumentation test class named <code>ExampleInstrumentedTest<code> inside your project’s <code>app/src/androidTest/<code> folder.
Next, implement the test function by adding the following:
With the instrumentation test in place to capture the screenshot, you can set up screengrab and then a lane to automate the screenshot generation process.
To install screengrab, add the Ruby gem:
Next, initialize screengrab by running the following inside your project:
To run screengrab, you need <code>-debug.apk<code> and <code>-debug-AndroidTest.apk<code>, but you can generate them automatically by building your project with the <code>./gradlew assembleDebug assembleAndroidTest<code> Gradle task. After a successful build, you can find both the APKs inside the project’s <code>/app.build/outputs/apk/<code>.
Next, find the <code>Screengrabfile<code> inside your <code>fastlane<code> directory. Open the Screengrabfile and replace its contents with the following:
screengrab is now configured, so once you add it to a lane, fastlane will be able to automatically capture and store screenshots of your app.
Open your Fastfile and add a new lane to create screenshots:
To run this lane and create new screenshots, use the following command:
This will start the screenshot-grabbing process. When the execution is completed, it will open the screenshots in your browser, but you can also find them inside the <code>/fastfile/metadata/<code> directory. Later in this tutorial, you’ll see how to upload these screenshots (with all your metadata) to the Google Play Store for distribution.
Before you distribute updates of your app to production users, you may want to share them with beta testers to get feedback. To do that, you can upload your Android app to an app distribution provider. fastlane supports beta app deployment with multiple beta app providers, including Google Play and Firebase App Distribution.
In this tutorial, I’ll show you how to distribute your beta app with Firebase App Distribution, which includes distribution and user management features for Android apps.
To get started, you have to add your project to Firebase.
After logging in, create a new project by clicking on Go to Console at the top right of your screen. Next, create a new Firebase project by clicking on Add project:
Name the project and continue. Once the project creation is complete, you can click on continue to view the project’s console.
Fastlane uses the Firebase CLI to upload your builds to Firebase App Distribution. Follow the instructions here to install Firebase CLI on your OS.
After the installation is complete, sign in to your Firebase account using the command below:
Before you continue, you also need to install the Firebase fastlane plugin:
Press y to allow fastlane to modify your Gemfile and continue.
After installing the plugin, you need to add Firebase to your Android app. Follow these steps to add Firebase to your project. Once Firebase is added, open the General Settings page and save your App ID so you can add it to your project’s configuration later.
Now you can create beta user groups and release your app to them before distributing to a wider audience in the Google Play Store. To create a user group, navigate to the App Distribution tab and press Get Started:
Go to the Testers and Groups tab and create a group. You can name it group-one.
Finally, add testers. Make sure you enter your own email to add yourself as a tester so you can try this out. Once that’s done, you are ready to upload your first beta build with fastlane.
Open your Fastfile and replace the <code>beta<code> lane with the following. Remember to replace <code><YOUR_FIREBASE_APP_ID><code> with the App ID you copied previously:
The above <code>beta<code> lane will upload your build to the group-one test group. From your terminal, run the <code>beta<code> lane with fastlane:
Navigate to Firebase App Distribution to ensure that the new build is available in your console:
The users in your test group also will receive an email with instructions:
Congratulations! You deployed your beta build to testers with fastlane.
Next time, you can make beta updates with a single command from your terminal, or you can hook this command into your continuous integration workflow to completely automate the process.
The last task we’re going to automate is releasing a new version of your app to users through the Google Play Store. Before you complete these steps, you’ll need to get a Google Play account (which you can sign up for here).
Fastlane uses the supply action to upload app metadata, screenshots, and binaries to Google Play. supply needs to have at least one previous version of your app uploaded to the Google Play Store before you run it because fastlane cannot create a completely new app in the Play Store. But after you’ve created your app manually the first time, fastlane can completely automate the update process, as you’ll see below.
You can follow the steps on the official Play Console Help page to create and set up your app for the first time. Once you have created your app in the Play Console, upload it to one of the available tracks so that Play Console knows your app’s package name. You don’t need to actually publish the app if you’re not ready to do so yet.
Next, Android requires that all APKs or app bundles be digitally signed with a certificate before they are uploaded to Play Console. If you haven’t generated an upload key for your app yet, you can follow the steps here to create one.
Once you have your key, best practice is to remove signing information from your build files so it is not easily accessible to others. To do this, create a separate properties file to store that information, as you will refer to this in your build files.
Navigate to your app’s <code>build.gradle<code> file and add the following. Be sure to add a reference to the key.properties file inside <code>build.gradle<code> before the <code>android<code> block:
Now, you can configure a single signing configuration for your release build type:
Once you have completed your signing configuration, Gradle will automatically sign each release when it’s built.
Currently, Android App Bundles are preferred over APKs. fastlane supports both, but you’ll need to update your Fastfile to build the app bundle for you.
To do so, add the following lane:
Next, execute the lane:
Once the execution is completed, you can find your bundle in the app’s build directory (the default location is <code>app/build/outputs/bundle/release<code>). Now you have an app bundle file that is ready to upload to the Google Play Console. While you’ll automate subsequent releases with fastlane, you have to upload this first build manually.
Go to Play Console, select the Production track, and create a release.
You can enable Play App Signing and upload the app-release.aab bundle file you previously created. Since this is the first upload of your app, you can provide a short description of it in Release notes.
Tap on save and navigate to All apps where your list of apps appears. Your new app will be available with your package name.
With your first build manually uploaded to the Play Store, you are ready to automate this process with fastlane for future updates.
To connect fastlane with Play Console, you need to provide appropriate credentials in the form of an API key file. This file contains the credentials that fastlane will use to connect to your Google Play Console account and make updates on your behalf.
To create a key file, follow these steps from the fastlane official documentation. Once your key file is created, you can connect fastlane with your Google Play Console APIs.
Run this command to verify your API key file:
Next, add your key file to fastlane. Open the <code>fastlane/Appfile<code> and update the <code>json_key_file<code> property with your key file location. In this tutorial, it is located inside the root directory of your project:
With the key file in place, you should be able to run supply to push the latest version of your app to the Google Play Store. Using an automated process like the one below is the best way to keep your metadata up-to-date with every release.
First, download your app’s existing metadata from the Play Store by running the following command. (Note: If you followed the previous steps on creating screenshots, you’ll already have a screenshot directory created. Remove that folder before initializing supply, as it will replace it the first time it runs.)
fastlane will download any existing content and put it into the <code>fastlane/metadata/android<code> directory. Next time you update your app’s metadata, you’ll only need to update these local files — supply will take care of the rest.
For example, to upload screenshots, first run the lane you created previously to generate screenshots:
Now, you will see your screenshots in <code>metadata/android/en-US/images/phoneScreenshots<code>. Run the following to upload your new screenshots:
The <code>--skip_upload_changelogs<code> property skips uploading changelogs so you do not have to increment your app’s version code when updating only metadata.
When the command runs successfully, navigate to the Play Console. On your app’s Main Store listing, you’ll see the screenshots:
You have now configured fastlane to retrieve and update app metadata, so the final step is to upload a release build to the Google Play Store.
In the previous section, you created an Android App Bundle and uploaded it to the Play Console manually. From now on, you can do that automatically by running a single command on your Terminal.
First, update the <code>deploy<code> lane inside your Fastfile:
The <code>release_status<code> property is used to maintain the status of the APKs or AABs when uploaded. You can find more parameters available for the supply action here.
Run <code>fastlane deploy<code>, and fastlane will take care of everything for your new release. When the command completes, your new build will appear in the Play Console.
In this tutorial, we’ve built a complete fastlane pipeline for Android app deployment. Hopefully you’ve seen how it can save you time over building, testing, and releasing apps manually. As you scale up your app development team and release efforts, automation tools become increasingly important, to prevent errors and ensure that no single team member becomes a bottleneck in the release process. Soon enough, your team will be spending more time building and iterating on your app instead of worrying about manual release tasks!