Sentry Android Gradle Plugin: Preserve Mapping Files for Release Reports

Apply the plugin to the app module

Start with the plugin version pinned in your root build configuration, version catalog or plugin-management block. Keep that selection compatible with the Android Gradle Plugin used by the project. In app/build.gradle.kts, apply io.sentry.android.gradle after the Android application plugin. The following example assumes its version has already been declared centrally; it is not a complete standalone Gradle project.

plugins {
    id("com.android.application")
    id("io.sentry.android.gradle")
}

sentry {
    org.set("example-team")
    projectName.set("android-client")
    authToken.set(System.getenv("SENTRY_AUTH_TOKEN"))
    includeProguardMapping.set(true)
    autoUploadProguardMapping.set(true)
}

Replace the two example slugs with the actual destination configured for your release diagnostics. Supply the upload token through the build environment. A runtime DSN and a build upload token serve different purposes; placing an upload credential in a string resource or BuildConfig would distribute it with the application. The official plugin repository and extension definitions document these option names. Check the corresponding tag for the version you actually pin.

Follow one minified release through the pipeline

Consider a release variant named demoRelease with code shrinking enabled. Build that variant and retain its resulting APK or bundle together with the mapping file generated by the same task execution. Record the application ID, version code, Git commit and SHA-256 of the distributable. A mapping file from a second rebuild is not a safe substitute simply because both builds display the same version name.

Inspect the build output for the variant-specific Sentry upload task and its result. Gradle task names depend on the plugin version and variant; list the available tasks rather than copying an assumed name from a different project. A skipped task needs explanation. It might indicate that the selected variant was excluded or that no matching mapping was produced. The word “successful” at the end of an unrelated build step does not establish that a mapping reached the intended project.

Keep the upload record with the archived artifact. For a CI failure, distinguish credential rejection, an incorrect organization or project, network failure, and a missing mapping input. Retrying a failed upload from the exact retained artifact is different from rebuilding the app and uploading a new mapping. Adopt the former when the release artifact is already fixed.

Check a known frame in a test release

Add a development-only trigger that calls a distinctly named method and reports a synthetic exception. Distribute that exact minified build to a test device, exercise the trigger and inspect the diagnostic event. The useful observation is whether the expected method and source location are recoverable for that artifact, not merely whether an event appears. Keep the trigger inaccessible in the production release.

If a managed-language frame resolves but a native frame does not, inspect the native symbol path separately. Java/Kotlin mappings do not describe machine addresses inside an ABI-specific shared library. Retain the unstripped native debugging artifacts appropriate to each distributed ABI, and verify that their identities correspond to the packaged binaries. Enabling source-context upload is another separate decision because it can disclose source files; it is not required merely to explain why a Java method was renamed.

For an independent local check, use Android's Retrace with the retained mapping and a captured obfuscated Java/Kotlin stack. If local retracing produces the expected method but the remote event remains obfuscated, focus on association and upload delivery. If both fail, investigate the mapping/artifact pairing first. This distinction makes the next repair concrete without guessing that every unreadable trace is a Sentry service problem.