Welcome to our Learn At Home Sale!

Limited-time Advanced Swift & Android book bundles, plus 50% off all books

Home · Android & Kotlin Tutorials

Fastlane Tutorial for Android: Getting Started

In this tutorial, you’ll learn how to use Fastlane to automate screenshots and metadata for your Android apps and build uploads to the Play Store.


  • Kotlin 1.3, Android 9.0, Android Studio 3.5

Imagine this: After a few weeks of development, your Android app is running smoothly in the emulator and on your friends’ devices. However, you know there are still enhancements to work on — and manually installing a new version is a lengthy process.

You also know that preparing for a launch takes time, so you want to start working on marketing material for the Play Store listing.

To start small, you decide to deliver an early version of your app to your closest customers. That’s where fastlane with Android can help. With this framework, you can automate a large part of the beta testing, submission and publishing stages of your app.

To test these services in different scenarios, you’ll create a Magic 8 Ball app called RWMagic8Ball that creates a random answer to a question.

In this tutorial, you’ll learn how to:

  • Set up fastlane in an existing project.
  • Automate app screenshots.
  • Distribute to beta testers with Firebase.
  • Upload marketing material from the command line.
  • Easily publish release notes.

Open Android Studio to begin.

Getting Started

First, download the starter project by using the Download Materials button at the top or the bottom of this tutorial.

Open the project in Android Studio then build and run. You’ll see something like this:

RWMaggic8Ball app's main screen, showing a Magic 8 Ball displaying,

This app contains one main functionality: It allows users to click an Ask button to create an answer and make decisions more quickly.

As you can see, it’s working smoothly. It’s ready for you to package it, upload it and send it to beta customers. :]

Before you can do those things, however, you must install and configure fastlane.

Installing Fastlane

In this section, you’ll install fastlane as a project dependency.

Before you can install fastlane, you must have Ruby version 2.5.1 or higher installed. Check the Ruby version by entering this command into Terminal:

ruby -v

If you haven’t already installed Ruby, or if your Ruby version is lower than 2.5.1, install a new version with Homebrew. See our Fastlane Tutorial: Getting Started for instructions.

You can manage multiple versions of Ruby with Ruby Version Manager (RVM). See installing RVM for more details.

Next, install fastlane as a project dependency. To do so, create a new file with no extension in the project’s root folder called Gemfile. Add the following:

source "https://rubygems.org"

gem "fastlane", "2.136.0"

Install the dependency using this command:

bundle install

Naming Your Package

Before you begin using fastlane, set a new package name across the app. The package name must be unique and it must remain unchanged in Google Play. The project will not run properly in later sections if you initialize fastlane before updating the package name.

Follow the steps described in the Getting Started section of the Android App Distribution Tutorial: From Zero to Google Play Store.

Build and run to verify that your app works correctly with its new, unique package name.

RWMaggic8Ball app's main screen, showing a Magic 8 Ball displaying,

Now, you’re ready to start working with fastlane.

Setting up Fastlane

In this section, you’ll follow the steps in the setting up fastlane documentation to initialize fastlane in a new project.

First, enter this command into Terminal:

bundle exec fastlane init

When prompted with Package Name (com.krausefx.app), enter your new package name.

Do not type anything for the Path to the json secret file. Press Enter.

At the prompt that asks, Do you plan on uploading metadata, screenshots and builds to Google Play using fastlane?, press n. You’ll set this option up later.

You’ve now created a new fastlane directory containing two files: Appfile and Fastfile. You’ll use them in the next sections to configure fastlane.

fastlane uses a Fastfile to store its automation configuration. Open Fastfile and you’ll see:


platform :android do
  desc "Runs all the tests"
  lane :test do
    gradle(task: "test")

  desc "Submit a new Beta Build to Crashlytics Beta"
  lane :beta do
    gradle(task: "clean assembleRelease")
    # sh "your_script.sh"
    # You can also use other beta testing services here

  desc "Deploy a new version to the Google Play"
  lane :deploy do
    gradle(task: "clean assembleRelease")

fastlane groups different actions into lanes. A lane starts with the lane :name statement, where name is the name given to a lane. Within that file, you’ll see three different lanes: test, beta and deploy.

Here’s a detailed explanation of the actions each lane performs:

  • test: Runs all the tests for the project. The gradle action runs all available gradle tasks for your project. You won’t use this lane in this tutorial.
  • beta: Submits a beta build to a Crashlytics. This lane uses the gradle action again, followed by the crashlytics action.
  • deploy: Deploys a new version to Google Play. This lane uses the gradle action again, followed by the upload_to_play_store action.
Note: Google has relaunched Crashlytics as Firebase App Distribution (previously available at http://try.crashlytics.com/beta/). You’ll configure fastlane with Firebase in a later section.

To run a lane, you must run fastlane <lane> where lane is the lane to execute.

In the rest of this tutorial, you’ll edit the available lanes with fastlane actions to customize RWMagic8Ball’s setup.

Editing the Building Lane

In the Fastfile, modify platform :android do to add a new build lane after the test lane:

desc "Build"
  lane :build do
    gradle(task: "clean assembleRelease")

Run the build lane from Terminal:

bundle exec fastlane build

If the command runs successfully, you’ll see the following at the end of the command output:

[13:37:40]: fastlane.tools finished successfully 🎉

Using Screengrab

Fastlane screengrab is an action that generates localized screenshots of your Android app for different device types and languages. In this section, you’ll learn how to use screengrab to create screenshots for the app.

In Android, you build screenshot automation over the Instrumentation Testing toolchain in Android, so your next step is to install the necessary dependencies.

Open app/build.gradle and add the following in the dependencies block:

  testImplementation 'junit:junit:4.12'

  androidTestImplementation 'com.android.support.test:runner:1.0.2'
  androidTestImplementation 'com.android.support.test:rules:1.0.2'
  androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'

  androidTestImplementation 'tools.fastlane:screengrab:1.2.0'

In app/build.gradle, add testInstrumentationRunner inside the defaultConfig block:

    testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"

Find the Instrumentation tests in app/src/androidTest/.

To create a new instrumentation test file, select the Android view in Android Studio’s Project navigator. Then, right-click on <your new package name> (androidTest) and select New ▸ Java Class:

Creating a new package in Android Studio’s Project navigator

For the Name input in the pop-up window, enter ExampleInstrumentedTest and click OK:

Entering the package's name in Android Studio’s Project navigator

Next, replace the contents of ExampleInstrumentedTest.java with the following. Make sure to change package to your new package name:

package <your-new-package-name>;

import org.junit.ClassRule;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

import android.support.test.rule.ActivityTestRule;
import tools.fastlane.screengrab.Screengrab;
import tools.fastlane.screengrab.UiAutomatorScreenshotStrategy;
import tools.fastlane.screengrab.locale.LocaleTestRule;

import static android.support.test.espresso.Espresso.onView;
import static android.support.test.espresso.action.ViewActions.click;
import static android.support.test.espresso.assertion.ViewAssertions.matches;
import static android.support.test.espresso.matcher.ViewMatchers.isDisplayed;
import static android.support.test.espresso.matcher.ViewMatchers.withId;

public class ExampleInstrumentedTest {

  public static final LocaleTestRule localeTestRule = new LocaleTestRule();

  public ActivityTestRule<MainActivity> activityRule = new ActivityTestRule<>(MainActivity.class, false, false);

  public void testTakeScreenshot() {
    // 1
    Screengrab.setDefaultScreenshotStrategy(new UiAutomatorScreenshotStrategy());
    // 2
    // 3
    // 4

The above code contains a JUnit 4 test. testTakeScreenshot performs the magic:

  1. Prepare to take a screenshot of the app.
  2. Take a screenshot of the first screen.
  3. Select the Ask button.
  4. Take another screenshot.

As with instrumentation testing on Android, you install a separate APK package, the test APK to drive the UI automation.

Run this command to assemble the Android test APK:

./gradlew assembleDebug assembleAndroidTest

When the command completes, you’ll see the test APK saved under app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk.

Also, run the following command to assemble the app APK:

./gradlew assembleDebug

Once the command completes, you’ll see the test APK saved under app/build/outputs/apk/debug/app-debug.apk.

Now that you’ve created the APKs, you’ll configure fastlane screengrab to create the screenshots.

Creating Screenshots

Automating screenshot generation saves a lot of time by allowing the configuration to be set once, and many screenshots can be taken thereafter. As mentioned in the fastlane documentation, you save the screengrab configuration inside a Screengrabfile.

Run the following command to create this file:

bundle exec fastlane screengrab init

Replace the contents of the fastlane/Screengrabfile with the following. Make sure to change app_package_name to your new package name:

# 1
# 2
locales(['en-US', 'fr-FR', 'it-IT'])
# 3
test_instrumentation_runner 'android.support.test.runner.AndroidJUnitRunner'

Here’s a description of the options:

  1. app_apk_path and tests_apk_path: The file path to the app APK and test APK files, which you created in the previous section.
  2. locales: The areas for which you want to create screenshots. Here, it creates screenshots for English, French and Italian locales.
  3. clear_previous_screenshots: If set to true, this clears all previously-generated screenshots in your local output directory before creating new ones.

Testing in an Emulator or Device

Now, start an emulator or device.

If you run an emulator with API 24 or above, you must configure it with the Google APIs target. An emulator with Google Play will not work because adb needs to run as root, and that’s only possible with the Google APIs target.

However, if you run a device or emulator with API 23 or below, it should work for both. See comment #15788 under fastlane issues for more information.

To check an existing emulator’s target, open AVD Manager and read the Target column:

Targets in the Your Virtual Device window

To create a new emulator with the Google APIs target, follow the wizard to create a new virtual machine. On the System Image page, select the x86 Images tab to see system images with Google APIs:

x86 Images tab on the System Image page

After the emulator or device starts, run this command in the project’s root folder to start the screenshot-grabbing process:

bundle exec fastlane screengrab

Your default browser will open a new tab to display the screenshots for each locale.

Different screenshots based on locale

Congratulations! You created screenshots for RWMagic8Ball with fastlane! This will really help you prepare to release your app on the Play Store.

But before you proceed to another topic, there’s one more step to finish: creating a lane to group multiple commands into one.

Adding a Lane

Open Fastfile and add the build_for_screengrab lane below the build lane:

desc "Build debug and test APK for screenshots"
lane :build_for_screengrab do
    task: 'clean'
    task: 'assemble',
    build_type: 'Debug'
    task: 'assemble',
    build_type: 'AndroidTest'

From now on, you can create new screenshots with two commands:

bundle exec fastlane build_for_screengrab
bundle exec fastlane screengrab

App Distribution

The beauty of fastlane is that you can easily switch to different beta providers, or even upload to multiple providers at once, with minimal configuration.

In the following sections, you’ll configure fastlane with two app distribution providers:

  • Beta Testing: Once you have a new feature ready, you’ll want to share it with beta testers to gather feedback before releasing on the Play Store. To do that, you’ll use the Firebase App Distribution service. Note that this service is currently in beta; it replaced the Crashlytics service.
  • Play Store: Fastlane provides the upload_to_play_store action to upload metadata, screenshots and binaries to the Play Store.

To upload a build to Google Play, use fastlane supply again.

Google Play provides different release tracks. This feature is useful if you wish to send a build to a selected set of early testers.

The available tracks are: open, closed, or internal test. More information is available from the Play Console Help docs.

The default value of the fastlane track parameter is production.

Using Firebase CLI

Note: This section will configure the project with Firebase App Distribution. Note that this service is currently in beta. Find out more about Firebase App Distribution on the official Firebase site.

Your next step is to distribute builds to testers with Firebase App Distribution. Although the Play Store provides similar functionality through the internal and beta tracks, you’ll see that Firebase App Distribution provides better user management and notification when you upload a new version of your app.

To use Firebase App Distribution, first create a Firebase project.

Visit the Firebase website. You’ll see something like this:

Firebase website main site

Log in using a Google account and take a quick look around the landing page.

To get started, click the Go to Console button on the upper-right side of the screen.

Create a new Firebase project by clicking on the Add project card:

White card with a plus symbol and the option to add a Firebase project

For this tutorial, use RWMagic8Ball for the project name. Your setup will look similar to this:

Adding the RWMagic8Ball project to Firebase

Read and accept the terms, if needed, and click Create Project. You’ll see a message that your new project is ready.

Click Continue to view the project dashboard.

When fastlane uploads a build to Firebase App Distribution, it uses the Firebase CLI to connect with the Firebase servers. Install or update to the latest version of Firebase CLI for your OS.

After the installation completes, run this command to sign into your Firebase account:

firebase login

Fastlane Plugin

You are now ready to configure fastlane with Firebase App Distribution.

Run the following command to install the firebase plugin for fastlane:

bundle exec fastlane add_plugin firebase_app_distribution

You’ll see a prompt like this:

[07:49:07]: Plugin 'fastlane-plugin-firebase_app_distribution' was added to './fastlane/Pluginfile'
[07:49:07]: It looks like fastlane plugins are not yet set up for this project.
[07:49:07]: fastlane will modify your existing Gemfile at path '/Users/jamesnocentini/Documents/project/rw/rwmagic8ball/RWMagic8Ball-final/Gemfile'
[07:49:07]: This change is necessary for fastlane plugins to work
[07:49:07]: Should fastlane modify the Gemfile at path
'/Users/jamesnocentini/Documents/project/rw/rwmagic8ball/RWMagic8Ball-final/Gemfile' for you? (y/n)

Press y to continue. You just installed the plugin.

Open the Firebase console to add the Android app to your project. Select your project and click the Add Firebase to your Android app card.

Click the Android icon to add Firebase to your Android app

Enter your new package name and click Register app. SHA key can be empty for now; you only need it when you are signing an APK.

Options to register your app with Firebase

Follow the instructions to add google-services.json to your project, then click Next.

Switch to Project view to add google-services.json to your project

Follow the instructions to add the Firebase SDK to your project and click Next.

Instructions to add the Firebase SDK to your project

Once installed, open the General Settings page for the project. Scroll down to the Your apps section. Write down the App ID — you’ll need it to configure fastlane later.

Location of the App ID in the Your apps section

Testing Groups

With Firebase App Distribution, you can create groups with different users and specify which group should receive each build release.

To implement this, navigate to the App Distribution tab:

Directions to access the App Distribution options

Go to the Testers and Groups tab and click Add group. Name the first group: Group one.

Next, click Add group again and add a second group named Group two. Click Add testers to add yourself as a tester and enter your email address.

Instructions showing where to add groups

You’re now ready to upload your first build with fastlane.

Deploying for Beta Testing

Open Fastfile and replace the beta lane with the following. Make sure to replace app with the App ID that you copied previously:

desc "Submit a new Beta Build to Firebase App Distribution"
lane :beta do

        app: "1:123456789:android:abcd1234",
        groups: "group-two",
        release_notes: "Lots of amazing new features to test out!"

The above code sets up the beta lane for the group-two test group. You can read more about the parameters available with the firebase_app_distribution action in the Firebase documentation.

Run the beta lane:

bundle exec fastlane beta

When the upload completes, you’ll see the following command output:

[08:28:48]: ---------------------------------------
[08:28:48]: --- Step: firebase_app_distribution ---
[08:28:48]: ---------------------------------------
[08:28:51]: ▸ i  getting app details...
[08:28:54]: ▸ i  uploading distribution...
[08:29:29]: ▸ ✔  uploaded distribution successfully!
[08:29:29]: ▸ i  adding release notes...
[08:29:30]: ▸ ✔  added release notes successfully
[08:29:30]: ▸ ⚠  no testers or groups specified, skipping

|                 fastlane summary                  |
| Step | Action                       | Time (in s) |
| 1    | default_platform             | 0           |
| 2    | Switch to android build lane | 0           |
| 3    | gradle                       | 53          |
| 4    | firebase_app_distribution    | 42          |

[08:29:31]: fastlane.tools finished successfully 🎉

The build is now visible on the Firebase App Distribution tab.

How to see your build in the Firebase App Distribution tab

Users in Group two will receive instructions by email to install the app, as shown:

Sending email instructions to install the new version of the app

Congratulations! You successfully used Firebase App Distribution for beta testing.

In the next section, you’ll learn how to do the same with the Google Play Console.

Creating Play Console Credentials

Note: This section requires you to configure your Google account with the Google Play Developer Console. There is a $25 charge to do so, which also lets you access all the Play Store’s features.

You can read more about associating an account and the registration fee on the Google Play Console website.

The project comes pre-configured with fastlane, but connecting it with the Play Store requires you to configure it with appropriate credentials. To do this, you’ll need an API key file. This is a JSON file that contains the credential data that fastlane uses internally to connect to your Play Store account.

To get one for your Play Store account, follow these steps from the fastlane documentation:

  • Open the Google Play Console.
  • In the menu on the left side of the page, click Settings. Then, click API access.
  • Scroll to the bottom of the API access page and click the CREATE SERVICE ACCOUNT button. This pop-up will appear:
    Create Service Account pop-up window
  • In the pop-up, click the Google API Console link. This opens a new browser tab or window:
    Window showing your Google Play Android Developer service accounts
    • Click the + CREATE SERVICE ACCOUNT button at the top of the Google Developers Console.
    • Provide a Service account name — for example, fastlane-rw.
    • Click the CREATE button.
    • In the Select a role drop-down, choose Service Accounts > Service Account User.
    • Then, click CONTINUE followed by + CREATE KEY.
    • Select JSON for the Key type on the right side of the page and then click CREATE.
    • Make a note of the file name of the JSON file that downloads to your computer.
  • Return to the browser tab or window with the Google Play Console.
    Create Service Account pop-up
  • Click DONE to close the dialog. Afterwards, you’ll see the API access page again:
    API access page
  • Click the Grant Access button for the newly-added service account.
  • Choose Release Manager or Project Lead from the Role drop-down. Note that choosing Release Manager grants access to the production track and all other tracks. Choosing Project Lead grants access to update all tracks except the production track.
  • Click ADD USER to close the dialog.

Congratulations! After you successfully complete those steps, you’ll see the newly-added user on the Users & permissions page:
New user on the Users & permissions page

Go back to the API access page and you’ll see:
Your new account and its permissions under Service accounts

You now have a credential file for fastlane to connect to the Play Console API. Run this command to test the connection with the downloaded private key:

bundle exec fastlane run validate_play_store_json_key json_key:/path/to/your/downloaded/file.json

To use it for the project, specify the path to that credential file in the Appfile, which you generated earlier in the tutorial.

Rename the private key file to api-play-store-key.json. Move it to the root directory of the project. Then, update fastlane/Appfile with the following line:


So your app is in good shape. Your next step is to try to upload it to the Play Console.

Uploading to Play Console

If you try to upload a build to the Play Store using the deploy command at this stage, it’ll fail. Give it a try:

bundle exec fastlane deploy

You’ll see the output:

[17:31:51]: Google Api Error: applicationNotFound: No application was found for the given package name. - No application was found for the given package name.

This message means that an app with that package name doesn’t exist on the Play Store Console yet.

fastlane with Android cannot create a new listing on the Play Store. Creating an app listing includes uploading the APK to one of the available tracks so the Play Console knows your app’s package name. You don’t need to publish the APK.

In the next section, you’ll create the app on the Play Store Console website.

Play Store Listing

To create a new app listing, open the Google Play Console and click CREATE APPLICATION.

All Applications screen on the Google Play Console

On the pop-up, leave the Default language input to its automatic value and provide an app name: RWMagic8Ball. Click CREATE.

Create application pop-up

You’ll see a screen with all the app information. Soon you’ll be able to use fastlane with Android to provide that data. For now, provide a short description and click Save Draft.

Return to the Applications tab. You should now see the RWMagic8Ball app in the list.

RWMagic8Ball appearing in the All applications window

Next, manually upload the first build on the Play Console so the Play Store can identify the app ID.

Select App releases from the left pane. Click the MANAGE button to open the Production track page.

Where to select App releases and the MANAGE button

Click Create release to upload a new build.

The Create release page

Scroll down to the Android App Bundles and APKs to add section to upload an APK. Click BROWSE FILES.

Android App Bundles and APKs to add section of the App releases page

Select the APK file that bundle exec fastlane build generates. It’s normally saved under app/build/outputs/apk/release/app-release.apk.

app-release.apk screen

Note: Android requires all APKs to be digitally signed with a certificate before you upload them to the Play Console.

The starter project comes pre-configured with app signing. If you’d like to configure app signing for a different app, follow the steps on the Android Studio user guide.

You must provide additional details before submitting the build. Since this is the first upload, the Release name can be anything such as 1.0 – 3. Provide a short description of the changes in this release, such as Lots of amazing new features to test out!.

Additional release information filled out

Click SAVE.

Next, return to the list of apps. This time, you’ll see your package name below the app name:

Your package name in the list of applications

From now on, when fastlane connects to the Play Store with your Google credentials, it’ll automatically find the app on the Play Store Console with your package name.

Downloading Metadata

In addition to uploading a build of your app, fastlane can upload app metadata such as screenshots, descriptions and release notes. This approach lets you keep a local copy of the metadata, check it in version control and upload it when you’re ready.

When you connect fastlane supply to the Play Store for the first time, you must run the init command, as the fastlane documentation describes.

The init command downloads the existing metadata to fastlane/metadata. If you followed the previous sections of this tutorial, it should already exist with app screenshots. Remove that folder for now; otherwise, this command will fail.

bundle exec fastlane supply init

This command downloads any existing content from the Play Store Console. When the command runs successfully, you’ll see the following output:

[✔] 🚀 
[13:48:36]: 🕗  Downloading metadata, images, screenshots...
[13:48:37]: 📝  Downloading metadata (en-GB)
[13:48:37]: Writing to fastlane/metadata/android/en-GB/title.txt...
[13:48:37]: Writing to fastlane/metadata/android/en-GB/short_description.txt...
[13:48:37]: Writing to fastlane/metadata/android/en-GB/full_description.txt...
[13:48:37]: Writing to fastlane/metadata/android/en-GB/video.txt...
[13:48:37]: 🖼️  Downloading images (en-GB)
[13:48:37]: Downloading `featureGraphic` for en-GB...
[13:48:38]: Downloading `icon` for en-GB...
[13:48:38]: Downloading `promoGraphic` for en-GB...
[13:48:39]: Downloading `tvBanner` for en-GB...
[13:48:39]: Downloading `phoneScreenshots` for en-GB...
[13:48:40]: Downloading `sevenInchScreenshots` for en-GB...
[13:48:40]: Downloading `tenInchScreenshots` for en-GB...
[13:48:41]: Downloading `tvScreenshots` for en-GB...
[13:48:41]: Downloading `wearScreenshots` for en-GB...
[13:48:43]: Found '1.0 - 3' in 'production' track.
[13:48:43]: 🔨  Downloading changelogs (en-GB, 1.0 - 3)
[13:48:43]: Writing to fastlane/metadata/android/en-GB/changelogs/1.0 - 3.txt...
[13:48:43]: ✅  Successfully stored metadata in 'fastlane/metadata/android'

The downloaded content saves in fastlane/metadata. Open android/en-GB/changelogs/1.0 – 3.txt and notice the same text that you entered on the Play Store Console.

The text,

Congratulations! You’ve set up a new app on the Play Store Console, configured fastlane and retrieved the app metadata.

Uploading Metadata

The next step is to update some metadata locally and upload it with fastlane — to provide app screenshots, for example. Run the lanes to create app screenshots:

bundle exec fastlane build_for_screengrab
bundle exec fastlane screengrab

Now, you’ll see two screenshots in metadata/android/phoneScreenshots:

Screenshots in the phoneScreenshots folder

Run fastlane supply again, this time without the init command to upload the new screenshots:

bundle exec fastlane supply --skip_upload_changelogs

Return to the Play Store Console. Select Store listing on the left pane, English (United States) in the Languages drop-down and scroll down to the Screenshots section. You’ll now see the screenshots that screengrab created:

Settings to import screenshots with screengrab

You can see that fastlane also enabled the French (France) – fr-FR and Italian – it-IT languages on the Play Store Console. That’s because screengrab created the fr-FR and it-IT folders in fastlane/metadata/android and supply detected those folders.

Where to Go From Here?

Congratulations on completing this tutorial! You’ve learned how to configure fastlane with Android in a sample app. You can download the final project by clicking the Download Materials button at the top or the bottom of this tutorial.

Fastlane can really help manage the mobile app release tasks. In addition to what you learned here, fastlane with Android also offers:

You can also learn more about the different app distribution providers:

Feel free to leave comments and suggestions in the forum below, especially about what you enjoyed and how we can improve the tutorial in the future! :]

Add a rating for this content

More like this