Getting started with Android apps

Abstract

Get started on Bitrise by signing up via email or a Git provider, connecting a repository, and running the first build for your Android app.

In this guide, we’ll walk you through how to add an Android app to Bitrise, what the default Workflows can do, and finally how to test and deploy your app to bitrise.io and to Google Play Store.

Do you have a Bitrise account?

Make sure you have signed up to bitrise.io and can access your Bitrise account. There are multiple ways of registering an account:

Adding an Android app to Bitrise

Log in to Bitrise and go to the Dashboard.
Click the Add New App button.
Under Project access, select the Workspace that will own the app.
Set the privacy of the app.

Caution

You cannot change this setting later! If you realize you've accidentally added your app as a public app even though you need it to be private, you'll have to delete the app and add it again.
- Private apps are only accessible to you, your Workspace members and those who are invited to work on an app. They require authentication to access the repository of the app.
- Public apps expose their bitrise.yml and their build logs to everyone. If you have a public app’s build URL, you can view its build log, to help with troubleshooting, for example. Public apps do not require authentication and they cannot have SSH keys.
Select one of two options to set your repository URL:
- With the Select remote repository option, you can select a repository from a list of repos from a connected Git provider account. Choose the Git provider from the dropdown menu, then click Select a repository... and select the repository from the list.
- The Enter URL manually option does not require a connected Git provider account: you can simply enter the URL and proceed to the authentication phase. We strongly recommend using an SSH URL, unless you are setting up a public app.
Repository URL

You will be able to change your project's repository URL later. You can also connect or disconnect your account to Git provider services at any time.

If you signed up for Bitrise using a Git provider account, that one is already connected and you can select any of your repositories from it.
Add an SSH key in the Authorize Bitrise section. This is only relevant for private apps: public apps can't have SSH keys and they don't require authentication. Choose from one of three options:
- Auto-add a generated SSH key to your repository: We recommend using this option. We automatically generate an SSH key pair and register the public key to your repository. Requires your connected Git provider account to have admin rights to the repository.
- Copy a generated SSH key to your Git provider manually: We generate an SSH key pair for you and you can copy the public key and register it manually to your Git provider. It is useful if, for example, you need to access multiple repositories with the same SSH key.
- Add your own SSH key to Bitrise: You can generate your own SSH key and paste the private key here after choosing this option. You also need to add the public key to the repository manually. To generate your SSH key pair: Generating your own SSH keypair.
Configure SSH keys at any time

If you can't set up a valid, working SSH key connection at this time, don't worry: proceed with adding your app. You can set up the SSH connection afterwards: Configuring SSH keys.
Select the default branch of your repository. This branch should contain the configuration of your project.
- If you successfully configured SSH access in the previous step or if you're adding a public app, Bitrise will parse your repository and allow you to select a branch from a dropdown menu.
- If you didn't configure repository access, you need to type the branch name manually.
You can change the default branch of the app later.
In the next step, choose Yes, auto-detect configuration. Bitrise will scan your repository and attempt to set up a stack and default Workflows based on the results of the scan. In most cases, we recommend choosing this option.

Project type

Detecting a project type serves to assist in the initial configuration of your app. But don't worry, you can change every setting, including the project type, at any time after you added the app.
Wait while Bitrise is validating your project. The scanner is looking for your build.gradle and gradlew files. If they are present, the project will be detected as an Android project.
The Bitrise Scanner selects the main module of your project by default. If there are more modules to choose from in the Module list, select a module that works best for your project.
Select a variant for building (you can Select All Variants which will generate all variants in Artifacts) and select a variant for testing too.
Register a webhook when prompted so that Bitrise can start a build automatically when code is pushed to your repository, or a pull request is created.
Once you are done, click View App Page to go to the newly added app's home page. From there, you can start editing your Workflows and run builds.

Managing dependencies for Android apps

The Gradle build system allows you include external binaries or other library modules as dependencies. Bitrise can install these dependencies for your app during the build process.

Adding build dependencies

You can read more about adding dependencies to your Android project: https://developer.android.com/studio/build/dependencies

Make sure your project's build.gradle file lists all your dependencies.
Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines page, find the Workflow you need.
Open the Workflow Editor.
Make sure your Workflow includes the Android Build Step.

If the project scanner generated a Workflow called deploy when first adding your app, that Workflow includes the Step. It installs all dependencies listed in the build.gradle file without any additional configuration.
Make sure your Workflow includes the Install missing Android SDK components Step.

The Step must be BEFORE the Android Build Step in the Workflow. It will install all Android SDK tool that your project might need.

Testing your Android app

We have several Steps dedicated to assisting you in testing your Android app during the CI process.

The Android Lint Step runs Lint on your Android project source files and detects potential syntax errors to keep your code error free.
The Android Unit Test Step runs your project's unit tests. You can run it for all your different modules and flavors. Running Android unit tests
The Virtual Device Testing for Android uses Firebase TestLab to run Android tests on virtual devices. Device testing for Android

The Android Unit Test Step and the Virtual Device Testing for Android Step can both export their results to the Test Reports add-on. To do so, simply make sure that your Workflow includes the Deploy to Bitrise.io Step at the very end of the Workflow.

Signing your Android app

In order to publish an Android app to Google Play, you need to digitally sign the app. Bitrise can also do this for you: you'll just need to upload a keystore file, and provide the necessary authentication.

Other code signing options

In this section, we'll go through how to sign an Android app with the Android Sign Step. There are other ways to sign your app - check out the other options in our relevant guides: Android code signing

Generate a keystore file.
Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
On the left, select Code signing from the menu.
Drag-and-drop your keystore file to the ANDROID KEYSTORE FILE field.
Fill out the Keystore password, Keystore alias, and Private key password fields and click Save metadata.
Open the Workflow Editor.
Add the Android Sign Step to your Workflow.

And that's it. The next time you'll run a build, the Android Sign Step will sign the generated binary.

Deploying an Android app to bitrise.io

In this section, we'll go through how to deploy your Android app to bitrise.io.

Deploying to bitrise.io means that the build artifacts generated during the build will be available for download once the build is finished. You can use this to test your app on your own test devices, for example.

To deploy your app to bitrise.io:

Workflow Editor

bitrise.yml

Make sure your Workflow contains the Android Build Step to build your app.

Optionally, you can build your app with the Gradle Runner Step. This requires a bit more configuration from you but allows for more extensive customization.
Add the Deploy to Bitrise.io Step to your Workflow.

Notifying other users

You can use the Notify: User Roles and the Notify: Emails inputs of the Step to set up notifications about your deploy. Click the input names to reveal more information about how to configure them.
Optionally, set the Enable public page for the App? input of the Step to true so the Step enables the public install page for your app.
Run a build.

Open the bitrise.yml file of your app.
Make sure your Workflow contains the android-build Step to build your app.
```
workflows:
  example-workflow:
    steps:
    - android-build@1:
```
Optionally, you can build your app with the gradle-runner Step. This requires a bit more configuration from you but allows for more extensive customization.

Set the module and/or variant input to tell the Step what to build.

In this example, we're building a debug variant of the Android project.

workflows:
  example-workflow:
    steps:
    - android-build@1:
        inputs:
        - variant: debug
    - deploy-to-bitrise-io: {}

Add the deploy-to-bitrise-io Step to your Workflow.
```
workflows:
  example-workflow:
    steps:
    - android-build@1:
        inputs:
        - variant: debug
    - deploy-to-bitrise-io: {}
```
Notifying other users

You can use the notify_user_groups and the notify_email_list inputs of the Step to set up notifications about your deploy:
- The notify_user_groups input allows you to send notifications based on the access roles granted to users. For example, you can set the input to notify everyone with an Admin and a Developer role. Set multiple roles separated by a comma: - notify_user_groups: admins, testers.
- The notify_email_list input only accepts Secrets, and the Secret should contain comma-separated lists of email addresses.
Optionally, set the Enable public page for the App? input of the Step to true so the Step enables the public install page for your app.
Run a build.

The Deploy to Bitrise.io Step will deploy the app. You can share the generated binary with your team members using the build’s URL.

Example 1. A bitrise.yml for deploying an Android app to Bitrise

In this example, we're building the debug variant of an Android app, and deploy it to bitrise.io, as.

Setting up Google Play deployment for the first time

Deploying to Google play publishes your app to Google's online store. When you do it for the first time, this requires a bit more work than simply deploying to bitrise.io. Once the necessary configurations are in place, it becomes very simple.

When configuring Google Play deployment for the first time, you need to link your Google Play Developer account to an API project, set up API access, and upload the service account JSON key to Bitrise.

Upload the first AAB or APK manually to Google Play using the Google Play Console.
Link your Google Play Developer Console to an API project.
Set up API Access Clients using a service account: Please note when you create your service account on the Google Developer Console, you have to choose json as Key Type.
Grant the necessary rights to the service account with your Google Play Console. Go to Settings, then Users & permissions, then Invite new user. Due to the way the Google Play Publisher API works, you have to grant at least the following permissions to the service account:
- Access level: View app information.
- Release management: Manage production releases, manage testing track releases.
- Store presence: Edit store listing, pricing & distribution.
As an optional step, you can add translations to your Store Listing: Translate & localize your app.
Upload the service account JSON key to the Generic File Storage.

Deploying to Google Play

Deploying to Google Play requires a signed APK or AAB file and the Google Play Deploy Step.

Workflow Editor

bitrise.yml

If you're trying to deploy your app for the first time, make sure your Google Play configuration is set up correctly and that you uploaded your service account JSON key to Bitrise.

Uploading the service account JSON key file

We recommend uploading the service account JSON key to Bitrise but it is not mandatory: you can store it elsewhere and provide a direct link to it.
Open the Workflow Editor, and go to the Code Signing & Files tab.
In the Generic File Storage, find the uploaded service account JSON key and copy the secret Env Var under its name.

For example, BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL.
Open your Workflow and add the Google Play Deploy Step to it.
In the Service Account JSON key file path input, paste the Environment Variable you copied.
Direct path to the service account JSON key file

If you don't want to upload the service account JSON key to Bitrise, you can also add a file path right in the Step’s input field where the file path can be local or remote too:
- For a remote JSON key file you can provide any download location as value, for example, https://URL/TO/key.json.
- For a local JSON key file you can provide a file path url as value, for example, file://PATH/TO/key.json.
In the Package name input, add the package name of your app.
In the Track input, add the track where you want to deploy your APK (for example, alpha/beta/rollout/production or any custom track you set).

If you're trying to deploy your app for the first time, make sure your Google Play configuration is set up correctly and that you uploaded your service account JSON key to Bitrise.

Uploading the service account JSON key file

We recommend uploading the service account JSON key to Bitrise but it is not mandatory: you can store it elsewhere and provide a direct link to it.

Open your app's bitrise.yml file and add the google-play-deploy Step to it.

deploy-workflow:
  steps: 
  - google-play-deploy: 
      inputs:

In the service_account_json_key_path input, you need to provide the path to the service account JSON key file.

If you uploaded the file to Bitrise, you can find the Env Var storing its download URL in the Generic File Storage in the Workflow Editor.
```
deploy-workflow:
  steps: 
  - google-play-deploy: 
      inputs:   
      - service_account_json_key_path: "$BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL"
```
If you didn't upload your service account JSON key to Bitrise, you can set a direct path in the input. The file path can point to a local or a remote location.
- For a remote JSON key file you can provide any download location as value, for example, https://URL/TO/key.json.
- For a local JSON key file you can provide a file path url as value, for example, file://PATH/TO/key.json.

In the package input, add the package name of your app.

deploy-workflow:
  steps: 
  - google-play-deploy: 
      inputs:   
      - service_account_json_key_path: "$BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL"
      - package_name: myApp

In the track input, add the track where you want to deploy your app binary (for example, alpha/beta/rollout/production or any custom track you set).

deploy-workflow:
  steps: 
  - google-play-deploy: 
      inputs:   
      - service_account_json_key_path: "$BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL"
      - package_name: myApp
      - track: alpha

That’s all! Start or schedule a build and share the URL with external testers or distribute your app on an app store of your choice!

In this section:

Getting started with Android apps

Do you have a Bitrise account?

Adding an Android app to Bitrise

Caution

Repository URL

Configure SSH keys at any time

Project type