Introduction

Android build metadata is much easier to trust when it is generated from Git instead of edited by hand. A common setup is to derive versionCode from commit count or a CI build number, then include the short commit hash in versionName and BuildConfig so every build can be traced back to source.

Generate version information from Git

In a Groovy-based app/build.gradle, you can run small Git commands to obtain a short SHA and a commit count:

1def gitSha() {
2    return 'git rev-parse --short HEAD'.execute([], rootDir).text.trim()
3}
4
5def gitCommitCount() {
6    return 'git rev-list --count HEAD'.execute([], rootDir).text.trim().toInteger()
7}

Then wire those values into the Android configuration:

1android {
2    defaultConfig {
3        versionCode gitCommitCount()
4        versionName "1.0.${gitCommitCount()}-${gitSha()}"
5        buildConfigField "String", "GIT_SHA", "\"${gitSha()}\""
6    }
7}

That gives each build a numeric code for installs and a human-readable label that includes the source revision.

Why versionCode and commit hash should not be the same thing

versionCode exists for Android package upgrade ordering. It must be numeric and it must increase for every release you publish. A Git hash is great for traceability, but it is not ordered and should not be used as the raw versionCode.

The practical split is:

• use commit count or CI build number for versionCode
• use semantic version plus short hash for versionName
• expose the hash through BuildConfig for runtime diagnostics

That approach keeps Android installation rules and debugging needs separate.

Expose the hash inside the app

Once the build creates BuildConfig.GIT_SHA, app code can log or display it:

val versionLabel = "${BuildConfig.VERSION_NAME} (${BuildConfig.GIT_SHA})"
println(versionLabel)

This is especially useful in QA builds because bug reports can include the exact source revision without guesswork.

CI build numbers are often safer than raw commit count

git rev-list --count HEAD is convenient, but it has limitations. It can change unexpectedly if repository history is rewritten, and shallow CI checkouts can produce misleading counts.

For production release pipelines, many teams prefer:

• CI-provided monotonically increasing build number for versionCode
• Git short SHA for traceability

In that setup, Gradle becomes the place where build metadata is assembled, not the place where release ordering is invented.

Add fallbacks when Git is unavailable

Gradle scripts that call Git assume the build is running from a Git checkout. That may fail in source archives or unusual CI environments, so a fallback helps:

1def safeGitSha() {
2    try {
3        return 'git rev-parse --short HEAD'.execute([], rootDir).text.trim()
4    } catch (Exception ignored) {
5        return "nogit"
6    }
7}

You can use the same pattern for commit count if necessary.

Keep release policy predictable

If the app is distributed through Google Play, versionCode must never move backward for published builds. Auto-versioning is only useful if it respects that rule every time. For that reason, it is often better to keep a simple release policy for production and a slightly different scheme for local debug builds.

Common Pitfalls

• Using the Git hash directly as versionCode even though versionCode must be numeric and increasing.
• Relying on commit count without considering rebases or shallow clones.
• Assuming Git commands always work in every build environment.
• Generating commit metadata but never exposing it in the running app.
• Forgetting that Play Store releases require monotonically increasing versionCode values.

Summary

• Auto-versioning reduces manual mistakes and makes Android builds traceable.
• Use a numeric source such as commit count or CI build number for versionCode.
• Put the short Git SHA in versionName and BuildConfig for debugging visibility.
• Add fallbacks for environments where Git metadata is unavailable.
• Keep the release strategy compatible with Play Store upgrade rules.