Home · Android & Kotlin Tutorials

Fastlane Tutorial for Android: Getting Started

Learn how to use fastlane to automate tasks like generating screenshots, updating metadata for your Android apps and uploading apps to the Play Store.

5/5 2 Ratings


  • Kotlin 1.3, Android 9.0, Android Studio 4.0
Update note: Nishant Srivastava updated this tutorial. James Nocentini wrote the original.

Android app development has many aspects including making releases, taking screenshots and updating metadata in Google Play Store. The good news is that you can automate these tasks, letting developers spend their time doing more important things like adding features and fixing bugs.

Fastlane lets you do all that efficiently and repeatedly. It’s an open-source tool aimed at simplifying Android and iOS deployment. Fastlane lets you automate every aspect of your development and release workflows.

In this tutorial, you’ll learn how to automate common tasks using fastlane. By the end, you’ll know how to:

  • Set up fastlane in an existing project.
  • Automate app screenshots.
  • Use Firebase App Distribution to distribute your app to beta testers.
  • Upload marketing material from the command line.
  • Easily publish release notes or a changelog.

Getting Started

To begin, 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 the app. You’ll see something like this:
RWMaggic8Ball app's main screen, showing a Magic 8 Ball

This app allows users to click the ASK button and receive a random answer.

The app is ready for you to package it and share it with beta testers. It’s time to get started with those tasks!

Installing Fastlane

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

ruby -v

To install or update Ruby with Homebrew, see our iOS tutorial, Fastlane Tutorial: Getting Started, for instructions.

Next, install fastlane and execute the following command in Terminal:

sudo gem install fastlane -NV

Great, you’re ready to get started now!

Naming Your Package

Your package name must be unique in Google Play. Give the starter project a new package name before you start using fastlane.

To do this, follow the steps described in the Getting Started section of our tutorial, Android App Distribution Tutorial: From Zero to Google Play Store.

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

RWMaggic8Ball app's main screen, showing a Magic 8 Ball displaying The Answer Is Yes

Now, you’re ready to work 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:

Note: If you encounter any permission issues when executing a command, prefix the command with sudo.
fastlane init

When prompted with Package Name (com.krausefx.app), enter your app’s new, unique package name. For the sample app, it’s com.raywenderlich.android.rwmagic8ball.

When you see the prompt for the Path to the JSON secret file, press Enter to skip. You’ll handle this later.

Next, you’ll see the prompt: Do you plan on uploading metadata, screenshots and builds to Google Play using fastlane?. Press n. You’ll set up this option later.

You’ll receive several more prompts. Press Enter to continue. When you’re done, run this command to try your new fastlane setup:

fastlane test

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

Configuring 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 lane :name, where name is the name given to a lane. Within that file, you’ll see three different lanes: test, beta and deploy.

Here’s an explanation of the actions each lane performs:

  • test: Runs all the tests for the project using the Gradle action. You won’t use this lane in this tutorial.
  • beta: Submits a beta build to Firebase App Distribution using the gradle action followed by the crashlytics action.
  • deploy: Deploys a new version to Google Play using the gradle action followed by the upload_to_play_store action.

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

In the next sections, 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

When 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’s 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 it to create screenshots.

To use the screengrab tool, you need to install the command-line tool first:

sudo gem install screengrab

Next, you need to add the permissions below to AndroidManifest.xml:

 <!-- Allows unlocking your device and activating its screen so UI tests can succeed -->
  <uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <!-- Allows for storing and retrieving screenshots -->
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

  <!-- Allows changing locales -->
  <uses-permission xmlns:tools="http://schemas.android.com/tools"
    tools:ignore="ProtectedPermissions" />

Now that fastlane has the permissions it needs, you can move on to automation.

Setting up Screenshot Animation

In Android, you set up screenshot automation over the Instrumentation Testing toolchain. Before you can start, you need to install the necessary dependencies.

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

testImplementation 'junit:junit:4.13'

androidTestImplementation 'androidx.test.ext:junit:1.1.1'
androidTestImplementation 'androidx.test:rules:1.2.0'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'

androidTestImplementation 'tools.fastlane:screengrab:2.0.0'

Inside the defaultConfig block, add testInstrumentationRunner:

testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'

These dependencies are needed for fastlane to run the tests and perform the screenshots. Sync Gradle before moving on.

Setting up the Instrumentation Tests

Navigate to app/src/androidTest/ to find the instrumentation tests.

To create a new instrumentation test file, right-click on <your package name> and select New ▸ Kotlin File/Class:

Creating a new Kotlin file/class

For the Name in the pop-up window, enter ExampleInstrumentedTest, select Class and press Enter:

Naming and creating a class file

Next, implement ExampleInstrumentedTest by adding the following to the newly created class:

import androidx.test.espresso.Espresso
import androidx.test.espresso.action.ViewActions
import androidx.test.espresso.assertion.ViewAssertions
import androidx.test.espresso.matcher.ViewMatchers
import androidx.test.rule.ActivityTestRule
import org.junit.Rule
import org.junit.Test
import org.junit.runner.RunWith
import org.junit.runners.JUnit4
import tools.fastlane.screengrab.Screengrab
import tools.fastlane.screengrab.UiAutomatorScreenshotStrategy
import tools.fastlane.screengrab.locale.LocaleTestRule

class ExampleInstrumentedTest {

    // JVMField needed!
    @Rule @JvmField
    val localeTestRule = LocaleTestRule()

    var activityRule = ActivityTestRule(MainActivity::class.java, false, false)

    fun testTakeScreenshot() {


The code above contains a JUnit 4 test. The test function testTakeScreenshot() performs the magic. It:

  1. Prepares to take a screenshot of the app.
  2. Takes a screenshot of the first screen.
  3. Selects the Ask button and triggers a click on it.
  4. Takes another screenshot.

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

Run this command:

./gradlew assembleDebug assembleAndroidTest

This assembles and tests the APK.

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

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

Creating Screenshots

Automating the screenshot generation process saves a lot of time. Now, you’ll get to try it out.

As mentioned in the fastlane documentation, you’ll save the screengrab configuration inside a Screengrabfile.

Run the following command:

bundle exec fastlane screengrab init

This creates the screengrab file.

Now, replace the contents of the fastlane/Screengrabfile with the following:

# 1

# 2

# 3

# 4

# 5
locales(['en-US', 'fr-FR', 'it-IT'])

# 6

Here’s what’s happening:

  1. android_home: Sets the path to the Android SDK that has the command line tools.
  2. use_adb_root: Starts adb in root mode, giving you elevated permissions to writing to the device.
  3. app_package_name: Sets the unique package name of your app.
  4. 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.
  5. locales: Designates the areas where you want to create screenshots. Here, it creates screenshots for English, French and Italian locales.
  6. 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

To test, you need to start an emulator or device.

Note: If you run an emulator with API 24 or above, you must configure it with the Google APIs target. An emulator with Google Play won’t work because adb needs to run as root. That’s only possible with the Google APIs target.

However, if you run a device or emulator with API 23 or below, either option will work. 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

Next, you need to make sure you have adb and aapt in your path. There are many ways of setting up the path; these differ based on the OS you use. To set it up in your current terminal session, simply execute the code below, being sure to use the correct path as per your Android SDK setup:

# Path to Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk

# Path to Android platform tools (adb, fastboot, etc)

# Path to Android tools (aapt, apksigner, zipalign, etc)
export ANDROID_TOOLS="$ANDROID_HOME/build-tools/29.0.3/"

# Add all to the path

Here, you’re making sure all tools under the Android SDK are available in the path.

Notice ANDROID_TOOLS references the build-tools folder for version 29.0.3. Make sure to specify the version you have.

After the emulator or device starts, run this command in the project’s root folder:

bundle exec fastlane screengrab

This starts the screenshot-grabbing process. Right now, it will throw errors; just ignore them. Eventually, it will complete and your default browser will open a new tab to display the screenshots for each locale.

Different screenshots based on locale

Congratulations! You’ve created screenshots for RWMagic8Ball with fastlane for the Play Store!

But before you proceed to the next 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 below commands:

bundle exec fastlane build_for_screengrab && bundle exec fastlane screengrab

Perfect. Now, it’s time to distribute your app!

Automating 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. Read more on the official Firebase site.
  • 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 the fastlane supply action.

Google Play provides different release tracks, which comes in handy when you want to send a build to a selected set of early testers.

The available tracks are: open, closed and 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

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 a better user management experience 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

To get started, click the Go to Console button on the upper-right side of the screen. You might need to sign in with Google.

Create a new Firebase project by clicking on Add project:

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 in to your Firebase account:

firebase login

Installing the Fastlane Plugin

You’re now ready to configure fastlane with Firebase App Distribution.

Run the following command:

bundle exec fastlane add_plugin firebase_app_distribution

This installs the firebase plugin for fastlane.

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 and install the plugin.

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

Click the Android icon to add Firebase to your Android app

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

Options to register your app with Firebase

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

Adding google-services.json to your project

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

Adding 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

Now, you’re ready to use Firebase to send different builds of your app to different groups of testers.

Testing Groups

Firebase App Distribution lets you 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.

Finally, click Add testers and enter your email address to add yourself as a tester.

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, making sure to replace app with the App ID 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 code above sets up the beta lane for the group-two test group. You can read more about the available parameters in 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.

Seeing your build in the Firebase App Distribution tab

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

Email instructions to install the new version of the app

Congratulations! You 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 to connect it with the Play Store, you need to configure it with the 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 Product Lead from the Role drop-down. Note that choosing Release Manager grants access to the production track and all other tracks. Choosing Product Lead grants access to update all tracks except the production track.
  • Click ADD USER to close the dialog.

Congratulations! After you 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 with its permissions:

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:

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

This tests the connection with the private key you downloaded.

To use the key in this 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:


Done! Your next step is 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 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.

Creating a 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.

You’ll see a screen with all the app’s 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 in the All applications window

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

Manually Updating a Build on the Play Console

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 Android App Bundles and APKs to add 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 generated. 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 from the Android Studio user guide.

You must provide some additional details before submitting the build. Since this is the first upload, the Release name can be anything; in this case, use 1.0 – 3. Provide a short description of the changes in this release. For now, use 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 apps

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 including 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, that directory will already exist and contain app screenshots. Remove that folder for now; otherwise, the following command will fail.

Now, run:

bundle exec fastlane supply init

This command downloads any existing content from the Play Store Console. Once 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]: 🖼️  Downloading images (en-GB)
[13:48:37]: Downloading `featureGraphic` for en-GB...
[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 it contains the text that you entered on the Play Store Console:

The text, Lots of exciting new features to test out!, in android/en-GB/changelogs/1.0 – 3.txt

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

Uploading Metadata

Your 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

In the Play Store Console, select Store listing on the left pane and English (United States) in the Languages drop-down, then scroll down to the Screenshots section. You’ll 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! You’ve learned how to configure fastlane in an Android app. You can download the final project by clicking the Download Materials button at the top or the bottom of this tutorial.

If you run the final app right away you’ll see the following error message:
File google-services.json is missing. The Google Services Plugin cannot function without it

Provide a valid google-services.json file for it to work.

Fastlane is a big help in managing 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 let us know what you enjoyed and how we can improve the tutorial in the future by leaving comments in the forumn below!

Average Rating


Add a rating for this content

2 ratings

More like this