Android tips and tricks

Gradle Runner vs Android Build

We’d like to shed light on the major differences between our two Android build steps: Gradle Runner and Android Build Steps. They are both build steps but they are slightly different in their functions. Let’s jump right in!

Our Gradle Runner Step is the headquarter for all your gradle tasks. It runs a single or multiple Gradle task(s) you specify and then copies the generated APK(s) or Android App Bundle(s) into the Bitrise Deploy Directory ($BITRISE_DEPLOY_DIR). This step runs ANY Gradle task (not just building task) that is available in your project’s task list. You can run multiple tasks at the same time if you insert the tasks separated with spaces in the Gradle task to run input field of the Step.

For example: assembleDebug assembleDebugAndroidTest where Gradle Runner step will output as many APK paths as many assemble tasks you have set.

Our Android Build Step is different from Gradle Runner in the sense that it provides a simplified user experience of Android Studio’s developing functions: it reflects how you would configure your project in Android Studio. This step is geared towards ONLY building your project, therefore, it cannot perform any othergradle task (as opposed to Gradle Runner). As a result, you can use assemble - related task with this Step.

About Gradle tasks

Gradle tasks are an integral part of Gradle build script. You can use any task that is defined in gradle build files where tasks are either specified by you or available by default based on your project. You can run these available tasks with the gradlew TASK-TO-RUN command in your Command Line / Terminal.

Here is a list of the most common default tasks of an Android Gradle project:

About Gradle Wrapper

At Bitrise we use gradlew (Gradle Wrapper) which helps update your project by installing the needed Gradle version specific to your project. Check out Gradle’s official documentation about Gradle Wrapper and how you can generate one!

Getting the list of available Gradlew tasks in your project

To get the basic task list, call gradlew tasks in your Android app’s directory. When running gradlew tasks, you’ll get a list of available and most frequently used gradle tasks in this format:

$ ./gradlew tasks


All tasks runnable from root project

Android tasks
androidDependencies - Displays the Android dependencies of the project.
signingReport - Displays the signing info for each variant.
sourceSets - Prints out all the source sets defined in this project.

Build tasks
assemble - Assembles all variants of all applications and secondary packages.
assembleAndroidTest - Assembles all the Test applications.
assembleDebug - Assembles all Debug builds.
assembleRelease - Assembles all Release builds.

To see all the available tasks listed in your task list, call ./gradlew tasks --all.

Running Gradle task with our Steps

You can run gradle tasks on Bitrise using Do anything with our Script Step, Gradle Runner and Android Build Steps.

Do anything with Script step

  1. Insert the Step anywhere in your workflow.
  2. Run any task by calling ./gradlew task-name-to-run in the Script input field (for example: ./gradlew assemble).
  3. Make sure the right executor type is selected to run your script in the Execution with / runner binary input field of the Config section.

Gradle Runner Step

As a minimum input, make sure you fill out the following two input fields:

  1. Specify the task that is available in your task list as the value of the Gradle task to run step input.
  2. If you use our scanner to upload your project to, the gradlew file path input field gets automatically filled out with the respective path in the Step. Otherwise make sure you fill it out manually and make sure to add a relative path to the repository root, for example: ./gradlew or ./sub/dir/gradlew (if it is a subdirectory).

Android tips and tricks

Android Build Step

This Step can only perform building-related gradle tasks. If you wish to run other type of gradle tasks, please use our Gradle Runner Step.

  1. Add the Step after the testing steps but before the code signing Step in your deploy workflow.
  2. Set the required Project Location input field to reflect the root directory of your project.

How to install an additional Android SDK package

You can update your Android SDK package or install missing dependencies either using our Install missing Android SDK components Step or Do anything with Script step where installing the respective package requires a little manual coding.

Automatic installation of Android SDKs and dependencies

We suggest using our Install missing Android SDK components Step to install dependencies and missing Android SDK components for your Android project:

  1. Provide the required NDK version in the NDK Revision input field. Leave this input empty if you are not using NDK in your project.

    Android tips and tricks

The Step runs the gradlew dependencies command and prints out a list of dependencies and SDK components that are relevant to your project. Then the Step takes care of installing them.

Manual installation of Android SDKs

As an alternative to the Install missing Android SDK components Step you can manually install the missing Android SDKs as well.

When to use Do anything with our Script step

Please only use the Do anything with Script step solution if you really need an alternative to the Install missing Android SDK components Step, as you’ll have to manually update the Script content if the Android tools change.

Before you start:

  1. Add Do anything with Script step (can be the very first step) to your workflow.
  2. Add the required platform and build-tools version to the Script content. In this example, we’re installing the Android SDK v18 and the related build-tools with v18.0.1.

    #fail if any commands fails
    set -e
    #debug log_
    set -x
    #write your script here
    sdkmanager "platforms;android-18"
    sdkmanager "build-tools;18.0.1"

You can check the full list of available packages (including obsolete packages) that you have already installed by running an sdk task:

  1. Run sdkmanager --list --include_obsolete --verbose command. You can run this command on your own machine if you have $ANDROID_HOME/tools/bin in your $PATH. If not, then you can run it with /PATH/TO/ANDROID-SDK-HOME/tools/bin/sdkmanager ....

Enabling Gradle debug options

If your Gradle build fails, we recommend you to first check your build’s log in the APPS & ARTIFACTS tab.

If you’re still lost, you can call --stacktrace --debug flags (for example, gradle ... --stacktrace --debug) to get more detailed logs.

In most cases --stacktrace should be enough, and the Gradle Runner Step includes this flag by default.

Android tips and tricks

Running a bitrise Android build on your Mac/PC with Docker

You can run your build on your Mac/PC inside the same docker container you use on to fully test your build in an identical environment! You can find the detailed guide here: How to run your build locally in Docker

Heap size

There are several options to adjust the heap size for the Java Virtual Machine (JVM). One option is adding Environment Variables (Env Vars) to your workflow where you specify the -Xms and -Xmx parameters. These determine heap size: the -Xms parameter sets the initial Java heap size and the -Xmx parameter sets the maximum Java heap size.

You can use the GRADLE_OPTS and JAVA_OPTS Env Vars to control JVM parameters by setting them in the Env Vars tab. This way the parameters will be applied to every Gradle and Android Step in every Workflow (unless you override them).


You can use our Android emulator Steps such as AVD Manager and Wait for Emulator to create and boot Android emulators. Let’s see how!

AVD Manager vs Do anything with Script step

Instead of using Do anything with Script step to create an Android emulator, please use AVD Manager Step! There are simply too many edge cases to cover relating to our Script Step, as well as the commands and working configurations change quite frequently.

  1. Add AVD manager Step to your workflow. It can be one of the first steps in your workflow.
  2. Set the following required input fields in the step: Device Profile, Android API level, and OS Tag.

    Android tips and tricks

    The Emulator needs some time to boot up. The earlier you place the Step in your workflow, the more tasks (cloning or caching) you can complete in your workflow before the emulator starts working.

  3. Add the Wait for Emulator Step to your workflow. This step acts a shield preventing the AVD Manager to kick in. Make sure you add it BEFORE the step with which you want to use the AVD Manager. In our example, we are using Wait for Android emulator Step to only start the Android Virtual Device FROM the Gradle Runner - UI test Step onwards.

    Android tips and tricks