Getting started with Android projects

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 project to Bitrise

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

Privacy is final

You cannot change this setting later! If you realize you've accidentally added your project as a public project even though you need it to be private, you'll have to delete the project and add it again.
- Private projects are only accessible to you, your Workspace members and those who are invited to work on a project. They require authentication to access the repository of the project.
- Public projects expose their bitrise.yml and their build logs to everyone. If you have a public project’s build URL, you can view its build log, to help with troubleshooting, for example. Public projects 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 project.
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.
If you use an OAuth connection, you need to add an SSH key in the Authorize Bitrise section.

You don't need SSH keys if:
- Your project is a public project.
- You connect to your Git repository via a GitHub project installation.
- 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 project. 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 project, 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 project 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 project. But don't worry, you can change every setting, including the project type, at any time after you added the project.
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 Project Page to go to the newly added project's home page. From there, you can start editing your Workflows and run builds.

Managing dependencies for Android projects

The Gradle build system allows you include external binaries or other library modules as dependencies. Bitrise can install these dependencies for your project 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.
Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
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.
Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
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 project 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 Android 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.
Connect your Google service account to Bitrise.

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 App settings page, and select Code Signing.
On the Android tab, 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 projects

Do you have a Bitrise account?

Adding an Android project to Bitrise

Privacy is final

Repository URL

Configure SSH keys at any time

Project type