Android Builds

Build and submit Android apps to Google Play Store using Capgo’s dedicated infrastructure.

What you will learn

• You will learn how to upload your app via Capgo Native build
• You will learn how to configure the credentials for Capgo Native Build

Prerequisites

• You need to have an active Google Developer account
• You need to have Android Studio installed
• Your app must be able to build successfully with Android Studio

Note

I will use the following app for the tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

The first manual build

Before we can start thinking about building the app with Capgo, we should first set it up, and do a first Android build by hand. There are some advantages to doing a manual build first:

• You will prepare the credentials for the later Capgo build
• You will create a record on the Play Store Console

Building the app manually with Android Studio

Before we can start building the app with Capgo, we need to build the app manually with Android Studio.

1. Open Android Studio

   Run bunx cap open android to open the Android Studio project.

2. Click on Build -> Generate Signed App Bundles / APKs

3. Select Android App Bundle and click on Next

Creating a Keystore

Right now, you are missing the keystore file. This file is used to sign your app, which lets Google know that it’s you who built the app. To generate it, we will use the GUI method provided by Android Studio. There is also a way to do this with the command line, but we will not cover that in this tutorial.

1. Click on Create new

2. Fill in the Key Store path

   Caution

   This IS TO BE SAVED - it will be used later

3. Set the Key Store password

   Note

   I recommend using the same password for the Key Store and the Key Alias.

   Caution

   This IS TO BE SAVED - it will be used later

4. Fill the rest of the form

   1. Keep the Key Alias as is (key0)
   2. Fill the certificate details. I have filled it with fake details, but you should fill it with your own details.

   

5. Click on OK

Finishing the manual build

1. Make sure all of the details for the keystore have been filled in correctly and click on Next

2. Select the release build variant and click on Create

3. After the build succeeds, you should see the following screen

   1. This popup indicates that the build succeeded.
   2. Click on the locate button - this will open the file explorer and you should see the build there.

4. Make sure you can see the build in the file explorer

Creating the app on the Play Store Console

1. Go to Google Play Console

2. Select the correct developer account

3. Click on Create app

4. Choose the app name and the language

5. Select the app category and if the app is paid or free

6. Accept the terms and conditions

   Caution

   Make sure you read the terms and conditions before accepting them.

7. Click on Create

Creating the internal testing group

Now that you have created the app, you can create an internal testing group. Since I won’t actually publish the app for everyone on Play Store, I will need to create an internal testing group. However, if you are going to publish the app for everyone, you can likely skip this step, although I don’t recommend it.

1. Go to internal testing Click on Test and release -> Testing -> Internal testing

   

2. Click on Testers

3. Click on Create email list

4. Name the email list

5. Add the email addresses of the testers

6. Press Enter and click on Save

7. Click on Create group

8. Make sure that the new list is selected and click on Save

Uploading the app to the internal testing group

Now that you have created the internal testing group, you can upload the app to the internal testing group.

1. Go to Test and release -> Testing -> Internal testing

2. Click on the Releases button

3. Click on Create new release

4. Click on Upload

5. Select the AAB (or APK) file

   Caution

   Make sure you select the AAB (or APK) file that you built manually with Android Studio. If this file doesn’t use the same keystore as the one you will use for the Capgo build, the Capgo Native Build will fail.

6. Wait for the AAB (or APK) file to be uploaded

7. Click on Next

8. Fix the errors

   Personally, at this stage I see this error

   

   This is because I haven’t verified my phone number yet. I will do that and continue the tutorial.

9. Click on Save and publish This will publish the app to the internal testing group.

10. Confirm the publication

11. Make sure the app is published

12. Get your temporary app name

Accept the invitation to internal testing group

Now that you have uploaded the app to the internal testing group, you can accept the invitation to the internal testing group.

1. Go to Test and release -> Testing -> Internal testing

2. Click on Testers

3. Click on Copy link

4. Send the link to your phone, open it in the browser and click on Accept

5. Confirm the invitation has been accepted and click on “download it on Play Store”

6. Install the app

   1. If you had installed the app before using Android Studio, click on the uninstall button
   2. Click on the install button
   3. Open the app and confirm it has downloaded successfully

   Caution

   If you do not see the app in Play Store, make sure you have selected the correct account in Play Store.

Configuring Capgo Native Build (Android)

Now, you are ready to start the setup of Capgo Native Build. Congratulations 🎉!

Requirement	Flag	Description	Required
Keystore file	--keystore <path>	Path to your .jks/.keystore file used to sign the APK/AAB.	Yes
Keystore alias	--keystore-alias <alias>	Alias name of the key inside the keystore.	Yes
Keystore key password	--keystore-key-password <password>	Password for the key. If key/store passwords match, you can provide only one.	Look at the note below
Keystore store password	--keystore-store-password <password>	Password for the keystore. If key/store passwords match, you can provide only one.	Look at the note below
Google Play service account	--play-config <path>	JSON service account file for Play Store uploads.	Yes

bunx @capgo/cli build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Note

If key and store passwords are identical, provide only one of --keystore-key-password or --keystore-store-password.

Keystore, keystore password, keystore key password, keystore alias

If you have followed the manual build instructions, you should have the keystore already generated. If you have not followed the instructions, please follow them to generate the keystore.

Google Play service account

Generating the Google Play service account is a manual and complex process. Yet, it is required to upload your app to Google Play. Please keep in mind the following things:

• You NEED to be the owner of the Developer Account. Otherwise, you will not be able to setup the service account.
• You will need to create a new Google Cloud Project (separate from your Google Play Account)

Let’s begin.

1. Go to Google Cloud Console

2. Click on the project selector

3. If you already have a project, select it. Otherwise, create a new project:

   Note

   The screenshots below are illustrative - use a name appropriate for your project.

   1. Click on New project
   2. Name your project and click Create
   3. Ensure that you are on the right project

4. Let’s click on the search bar and search for service accounts and click on it

5. Let’s click on Create service account

6. Fill in the form for the service account and click on Done

   1. I recommend setting the name to Capgo Native Build Service Account
   2. For the Service Account ID, I recommend setting it to capgo-native-build-service-acc
   3. As for the description, you don’t have to fill it in, but I recommend filling it with Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Click on the newly created service account You should now see the newly created service account in the list. Click on it.

   Note

   Copy this email address as well, you will need it later.

8. Click on the Keys tab

9. Click on Add Key and Create new key

10. Click on JSON and Create

    Caution

    Clicking on Create will create a new key and it will download the JSON file to your local machine.

    You need to save the JSON file in a safe place. It WILL be used later.

11. Download the JSON file The JSON file should have been downloaded automatically. You can click on close to close the window.

Granting Play Store API access to the service account

The newly created service account does not yet have access to the Play Store API. To grant it, head to the Play Store Console.

1. Go to Google Play Console
2. Select the correct developer account
3. Click on Users and permissions
4. Click on Invite new users
5. Copy the email address of the service account
6. Go to Account permissions and grant the minimum required permissions:
   • In App permissions, grant access to your app.
   • In Releases, enable Create, edit, and roll out releases.
   • If your workflow uses Play App Signing, enable the related signing permission.
   • If you are unsure, use Admin only during setup, then reduce permissions afterward.
7. Click on Invite user
8. Confirm the invitation
9. Confirm that the user has been invited

Saving the credentials

You are now ready to save the credentials and run your first build. You can save the credentials using the following command:

bunx @capgo/cli build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD setup (GitHub Actions)

If you already completed Keystore, keystore password, keystore key password, keystore alias and Google Play service account, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

1) Convert credential files to single-line base64

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

Tip

GitHub secrets should be single-line values. tr -d '\n' removes line breaks from base64 output.

2) Create repository secrets

In GitHub > Repository > Settings > Secrets and variables > Actions, add:

Secret name	Value
CAPGO_TOKEN	Your Capgo API token
APP_ID	Your Capgo app ID (example: com.example.app)
ANDROID_KEYSTORE_FILE	Content of keystore_base64.txt
KEYSTORE_KEY_ALIAS	Keystore alias from Keystore, keystore password, keystore key password, keystore alias
KEYSTORE_KEY_PASSWORD	Keystore key password
KEYSTORE_STORE_PASSWORD	Keystore store password
PLAY_CONFIG_JSON	Content of play_config_base64.txt

Note

If key and store passwords are the same, you can provide just one of KEYSTORE_KEY_PASSWORD or KEYSTORE_STORE_PASSWORD.

3) Use env vars in your GitHub Actions workflow

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

Tip

With this setup, CI sends credentials through environment variables only. You do not need to commit signing files or upload them as workflow artifacts.

Running the build

Congratulations 🎉! You are now ready to run your first build.

Run:

bunx @capgo/cli build com.example.app --platform android

And this will start the build process 🍾🥂