Android Certificates Setup

Complete guide to creating the Android signing keystore and Google Play service account required for building and publishing Android apps with Capgo Cloud Build.

Overview

To build and publish Android apps, you need:

1. Signing Keystore (.keystore or .jks file) - Signs your app for release
2. Google Play Service Account (.json file) - For automatic Play Store uploads

What You'll Create

• Android Keystore file (.keystore or .jks)
• Google Play Service Account JSON

Requirements

• Java JDK installed (for keytool)
• Google Play Console account
• App already registered in Play Console

Keep Your Keystore Safe!

Your keystore is irreplaceable. If you lose it or forget the passwords, you cannot update your app on the Play Store - you’ll need to create a new app listing.

Store your keystore file and passwords in multiple secure locations (password manager, secure backup, etc.).

Part 1: Create a Signing Keystore

The keystore contains your private key used to sign your Android app. Every update to your app on the Play Store must be signed with the same key.

Command Line

Using keytool (Recommended)

The keytool command is included with Java JDK. Open your terminal:

keytool -genkey -v \
  -keystore my-release-key.keystore \
  -alias my-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

You’ll be prompted for:

Prompt	Description	Example
Keystore password	Password to open the keystore file	MySecurePassword123!
Key password	Password for this specific key (can be same as keystore)	MySecurePassword123!
First and last name	Your name or company name	John Doe
Organizational unit	Department (optional)	Mobile Development
Organization	Company name	My Company Inc.
City	Your city	San Francisco
State	Your state/province	California
Country code	Two-letter country code	US

提示

Password tip: You can use the same password for both the keystore and the key. If you do, you only need to set KEYSTORE_KEY_PASSWORD in Capgo - it will use the same value for KEYSTORE_STORE_PASSWORD.

After completing the prompts, you’ll have a my-release-key.keystore file.

Android Studio

Using Android Studio

1. Open Android Studio

   Open any project or create a new one.

2. Open the Build menu

   Go to Build → Generate Signed Bundle / APK

3. Choose APK or Bundle

   Select Android App Bundle or APK and click Next.

4. Create new keystore

   Click “Create new…” to create a new keystore.

5. Fill in keystore details

   • Key store path: Choose where to save the .jks file
   • Password: Enter a strong keystore password
   • Confirm: Re-enter the password
   • Alias: Enter a name for your key (e.g., release-key)
   • Key password: Password for the key (can be same as keystore)
   • Validity: Number of years (25 is recommended)
   • Certificate: Fill in your name, organization, and location

6. Complete the wizard

   Click OK to create the keystore, then finish or cancel the build wizard.

Understanding Keystore Components

When saving credentials for Capgo, you’ll need these values:

Value	Environment Variable	Description
Keystore file	ANDROID_KEYSTORE_FILE	Base64-encoded keystore file
Keystore password	KEYSTORE_STORE_PASSWORD	Password to open the keystore
Key alias	KEYSTORE_KEY_ALIAS	Name of your key in the keystore
Key password	KEYSTORE_KEY_PASSWORD	Password for the specific key

Verify Your Keystore

Check that your keystore was created correctly:

# List all keys in the keystore
keytool -list -keystore my-release-key.keystore

# View detailed information about a specific key
keytool -list -v -keystore my-release-key.keystore -alias my-key-alias

You should see output showing your certificate details and expiration date.

Part 2: Create a Google Play Service Account

A service account allows Capgo to automatically upload your app to the Google Play Store.

1. Open Google Play Console

   Go to Google Play Console and sign in.

2. Navigate to API Access

   In the left sidebar, go to Setup → API access.

   注意

   If this is your first time, you may need to accept the Terms of Service and link to a Google Cloud project.

3. Create a new service account

   In the “Service accounts” section, click “Create new service account”.

   A dialog will appear with a link to Google Cloud Console.

4. Create the account in Google Cloud

   Click the link to open Google Cloud Console in a new tab.

   In Google Cloud Console:

   • Click ”+ Create Service Account”
   • Service account name: Enter a descriptive name (e.g., capgo-play-upload)
   • Service account ID: Auto-generated from the name
   • Description: Optional (e.g., Service account for Capgo CI/CD uploads)
   • Click “Create and Continue”

5. Skip the optional role assignment

   You don’t need to assign Google Cloud roles here. Click “Continue”, then “Done”.

6. Create a JSON key

   Find your new service account in the list and click on it.

   Go to the “Keys” tab:

   • Click “Add Key” → “Create new key”
   • Select “JSON” format
   • Click “Create”

   The JSON file will download automatically. Keep this file secure!

7. Grant Play Console permissions

   Go back to Google Play Console (the tab from step 3).

   Click “Refresh service accounts” or refresh the page.

   Find your new service account in the list and click “Manage Play Console permissions” (or “Grant access”).

8. Set app permissions

   On the permissions page:

   Under “App permissions”:

   • Click “Add app”
   • Select your app from the list
   • Click “Apply”

   Under “Account permissions” (for the app you selected):

   • Check “Releases” → “Create, edit, and delete draft releases”
   • Check “Releases” → “Release to production, exclude devices, and use Play App Signing”
   • Check “Releases” → “Release apps to testing tracks”

   Click “Invite user”.

9. Verify the invitation

   The service account should now appear in your users list with the permissions you granted.

   注意

   Service accounts don’t need to “accept” invitations like regular users. The permissions are granted immediately.

Required Permissions Summary

Your service account needs these minimum permissions:

Permission	Required For
Create, edit, and delete draft releases	Uploading new versions
Release to production, exclude devices, and use Play App Signing	Publishing to any track
Release apps to testing tracks	Publishing to internal/alpha/beta

Part 3: Save Credentials for Capgo

Now save your credentials for use with Capgo Cloud Build:

Using the CLI (Recommended)

npx @capgo/cli build credentials save \
  --platform android \
  --keystore ./my-release-key.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "YourKeyPassword" \
  --keystore-store-password "YourStorePassword" \
  --play-config ./play-store-service-account.json

提示

If your key password and store password are the same, you only need to provide one:

npx @capgo/cli build credentials save \
  --platform android \
  --keystore ./my-release-key.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "YourPassword" \
  --play-config ./play-store-service-account.json

Using Environment Variables

For CI/CD environments, encode files as base64 and set environment variables:

# Encode keystore to base64
base64 -i my-release-key.keystore | pbcopy

# Encode service account JSON to base64
base64 -i play-store-service-account.json | pbcopy

Set these environment variables in your CI/CD secrets:

Variable	Description
ANDROID_KEYSTORE_FILE	Base64-encoded keystore file
KEYSTORE_KEY_ALIAS	Key alias name in the keystore
KEYSTORE_KEY_PASSWORD	Password for the key
KEYSTORE_STORE_PASSWORD	Password for the keystore (optional if same as key password)
PLAY_CONFIG_JSON	Base64-encoded service account JSON

Verify Your Setup

Test that everything is configured correctly:

# List saved credentials
npx @capgo/cli build credentials list

# Run a debug build (no signing required)
npx @capgo/cli build com.example.app --platform android --build-mode debug

# Run a release build (requires signing)
npx @capgo/cli build com.example.app --platform android --build-mode release

Using Play App Signing

Google Play App Signing is recommended for enhanced security. When enabled:

• Google manages your app signing key
• You upload with an “upload key” (your keystore)
• Google re-signs with the actual app signing key

This is configured in the Play Console under Setup → App signing and doesn’t change how you use Capgo - you still provide your upload keystore.

Common Issues

”Keystore file not found”

Cause: Incorrect path to keystore file.

Solution: Verify the file path is correct and the file exists:

ls -la ./my-release-key.keystore

“Keystore password incorrect”

Cause: Wrong password entered.

Solution:

1. Double-check the password (copy-paste to avoid typos)
2. Verify which password is which:
   • KEYSTORE_STORE_PASSWORD: Opens the keystore file
   • KEYSTORE_KEY_PASSWORD: Accesses the specific key

Test with keytool:

keytool -list -keystore my-release-key.keystore
# Enter store password when prompted

“Alias does not exist”

Cause: Key alias name doesn’t match.

Solution: List all aliases in your keystore:

keytool -list -keystore my-release-key.keystore

The alias is case-sensitive - use it exactly as shown.

”Play Store upload failed”

Cause: Service account permissions issue.

Solution:

1. Verify the service account has correct permissions in Play Console
2. Check that the JSON file is the correct one (not a different service account)
3. Ensure your app exists in Play Console and has at least one manual upload
4. Wait 24 hours if you just set up the service account (permissions can take time to propagate)

“APK signature verification failed”

Cause: Signing with a different key than previous releases.

Solution:

• You must use the same keystore for all updates to an app
• If you lost your keystore and use Play App Signing, contact Google support
• If you lost your keystore without Play App Signing, you’ll need to create a new app listing

Security Best Practices

Keystore Security

1. Never commit to version control

   # Add to .gitignore
   echo "*.keystore" >> .gitignore
   echo "*.jks" >> .gitignore

2. Create backups

   • Store in a password manager (1Password, Bitwarden)
   • Keep encrypted backup in secure cloud storage
   • Document passwords separately from the keystore

3. Use strong passwords

   • Minimum 16 characters
   • Mix of letters, numbers, and symbols
   • Different from other passwords

Service Account Security

1. Limit permissions

   • Only grant permissions needed for uploads
   • Don’t grant financial or user data access

2. Never commit JSON to version control

   echo "*-service-account.json" >> .gitignore

3. Rotate if compromised

   • Delete the key in Google Cloud Console
   • Create a new service account if needed

Next Steps

• Build Android Apps - Start building with Capgo
• Managing Credentials - Credential management reference
• Troubleshooting - Common build issues

Need Help?

• Troubleshooting Guide
• Discord Community
• Email: support@capgo.app