32.2 Signing Configurations

Understanding Signing Configurations

Android requires every app to be digitally signed. A signing configuration is the set of information and files that Gradle and Android Studio use to apply a digital signature to your app during the build process. In this chapter you focus on how these configurations are defined, where they live, and how to use different configurations for debug and release builds.

Key Concepts: Keystore, Key, and Alias

A signing configuration is built around a keystore file. A keystore is a secure file, usually with a .jks extension, that stores one or more keys. Each key inside a keystore has a name called an alias. The actual cryptographic material is protected by a password.

When you define a signing configuration, you provide Gradle with the keystore path, keystore password, key alias, and key password. Gradle then uses this information at build time to sign your APK or AAB.

You typically have at least two keystores during development. Android Studio automatically creates and uses a debug keystore for development builds. You create your own private keystore for release builds. The signing configuration connects these keystores to your Gradle build types.

Debug vs Release Signing Configurations

Android Studio uses different signing configurations depending on the build type. A debug build uses a debug signing configuration. This is created automatically when you install Android Studio and is stored in a known location on your computer. The debug key is not secure and has a fixed validity period. Its only purpose is to let you run and test your app on devices and emulators.

A release build uses a release signing configuration. You must create and manage this yourself. This configuration uses your own keystore and key, with passwords and alias names that you choose. The release configuration is what you use for app packages that you intend to distribute.

In practice, the debug signing configuration is almost invisible to you. You run the app from Android Studio and it is signed automatically with the debug key. For release builds, you must explicitly select or define a signing configuration so that Gradle knows how to sign the final artifact.

Creating a Release Keystore from Android Studio

Android Studio provides a guided flow to create a keystore and related signing configuration. The details of where to click belong elsewhere, but the important part for signing configurations is the outcome of this process.

After you complete the wizard, you will have a physical keystore file on disk, a key alias inside that keystore, and passwords associated with them. You then connect this keystore to a Gradle signing configuration. The wizard can optionally update your module level build.gradle or build.gradle.kts file with the correct signing configuration block.

The created keystore should be stored in a safe, backed up location. The resulting signing configuration in Gradle will reference the keystore path and passwords, which you can later adjust and secure.

Signing Configurations in Gradle

In a typical Android project, signing configurations are defined inside the android block of your module level Gradle file. The structure is similar in Groovy and Kotlin DSL. Here is a simplified Groovy style example.

android {
    signingConfigs {
        release {
            storeFile file("/path/to/your/keystore.jks")
            storePassword "yourStorePassword"
            keyAlias "yourKeyAlias"
            keyPassword "yourKeyPassword"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            shrinkResources true
        }
        debug {
            // Usually uses the default debug keystore automatically
        }
    }
}

The signingConfigs block defines named configurations, such as release or any other label that you choose. Inside the block you specify the keystore file location and credentials. The buildTypes block then references a specific signing configuration with the signingConfig property.

In Kotlin DSL, the idea is exactly the same, but the syntax changes slightly.

android {
    signingConfigs {
        create("release") {
            storeFile = file("/path/to/your/keystore.jks")
            storePassword = "yourStorePassword"
            keyAlias = "yourKeyAlias"
            keyPassword = "yourKeyPassword"
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            isShrinkResources = true
        }
    }
}

The important part is that each build type that you plan to ship must be linked to an appropriate signing configuration. Without this link, Gradle cannot sign your release artifacts.

Using Environment Variables and secure properties

Placing raw passwords in your Gradle files is not recommended, especially if you use version control. Instead, you can move these values to a separate, untracked properties file or use environment variables.

A common approach is to store sensitive values in a keystore.properties file that is ignored by your version control system. You can then read that file from Gradle and apply its properties when creating the signing configuration.

Another approach is to use environment variables. You can reference them in your Gradle file and avoid checking any secret values into your repository. Regardless of the method, the goal is to keep the signing configuration definitions in Gradle while keeping sensitive data in a safe and private place.

Different Configurations for Different Flavors

Beyond simple debug and release build types, projects can define product flavors. Each flavor can have its own signing configuration. This is useful if you need to create multiple versions of your app for different clients, regions, or internal testing, each signed with a distinct key.

You can create multiple entries in the signingConfigs block, for example internal, beta, or clientX, and then assign them to specific flavor and build type combinations. Gradle lets you associate signing configs at the flavor level or override them at the build type level.

This flexibility allows complex release strategies without duplicating code. Every final variant that reaches users still has a single signing configuration, but the project can manage many configurations centrally.

Verifying and Changing Signing Configurations

After you define a signing configuration in Gradle, you can verify that your release builds are correctly signed by generating an APK or AAB and inspecting its signature with appropriate tools. Android Studio also shows which signing configuration is used when you build a release variant through its build output logs.

If you need to adjust a signing configuration, you can change the keystore path or passwords in your Gradle file or in your external properties file. In some cases, such as when migrating to a new signature management method, you may define a new signing configuration and assign it to a different build type or flavor.

While you can change signing configurations inside your project at any time, you must be careful with any configuration that is used for a published app. Changing the key that signs an already published app affects updates and may require special procedures.

Practical Workflow with Signing Configurations

In everyday Android development, signing configurations allow you to separate development builds from production builds and to automate the signing process. You set up your configurations once, keep your keystores and passwords secure, and then rely on Gradle to sign every build consistently.

During development, you usually interact with the debug configuration implicitly. For testing release behavior, you build a release variant and let Gradle apply the release signing configuration. For automated builds such as continuous integration, you place the keystore in a secure location, provide passwords through secure variables, and let the build scripts reuse the same configuration.

By keeping your signing configurations organized and secure, you create a predictable build process and protect the identity and integrity of your app as it moves toward distribution.