branchmark

Overview

Install three debug builds from three branches and they're indistinguishable on the launcher — same icon, same name. branchmark fixes that. For a branch like fix/login-crash it draws a red ribbon across the top-right corner reading LOGIN-CRASH, and a 🔧 emoji for the fix type in the lower-left.

It never asks you to supply a second icon. branchmark reads your app's existing mipmap-anydpi-v26/ic_launcher.xml, rasterizes its vector foreground, paints the banner on top, and generates a debug-only adaptive icon that overrides the original — release builds are untouched.

Installation

Add Maven Central to your plugin repositories in settings.gradle.kts:

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

Then apply the plugin in your Android application module, after the Android plugin:

plugins {
    id("com.android.application")
    id("com.rohittp.plugables.branchmark") version "1.0.0"
}

That's the whole setup. branchmark expects a standard adaptive icon (mipmap-anydpi-v26/ic_launcher.xml with a <foreground>), which Android Studio's New Project wizard generates by default.

How it works

On every debug build, the generateBranchmarkIcon task runs the following pipeline, once per density:

1. Parse src/main/res/mipmap-anydpi-v26/ic_launcher.xml and resolve its <foreground>, <background>, and <monochrome>.
2. Resolve the foreground to a bitmap — a vector drawable is rasterized with Android's own VdPreview at the 108dp canvas size for the density; a raster foreground is read directly.
3. Draw the ribbon (Java2D) and the prefix emoji (a bundled Twemoji color SVG, rasterized with Apache Batik) onto a copy of the foreground, keeping the glyph inside the adaptive-icon safe zone.
4. Write mipmap-<dpi>/ic_launcher_foreground_debug.png and a debug mipmap-anydpi-v26/ic_launcher.xml that points <foreground> at the stamped image while preserving your original background and monochrome.

The generated res directory is registered as a debug variant resource source, so AGP's resource merger overrides the icon for debug builds only.

Branch detection

Branches are read as .../<type>/<name> — only the final two slash-separated segments matter. The second-to-last segment is the type (chooses the emoji); the last segment is the name (the ribbon text). Any leading segments are ignored, so personal and team prefixes work without configuration.

The branch name itself is resolved with this precedence:

1. branchOverride (DSL)
2. -PgitBranch=… (Gradle property)
3. GITHUB_HEAD_REF (GitHub Actions PR builds)
4. GIT_BRANCH (common CI convention)
5. git rev-parse --abbrev-ref HEAD

Configuration

Every option has a sensible default — zero config works. The branchmark DSL block lets you override what you need:

branchmark {
    ribbonColor.set("#D32F2F")
    fallbackRibbonText.set("DEBUG")
    // additive emoji overrides — use put, not set
    emojiByPrefix.put("spike", "🧪")
}

Prefix emoji map

These branch types ship with a bundled color glyph out of the box. Any other type falls back to defaultEmoji (🌿).

CI setup

CI checkouts are often detached or shallow, so git can't report a branch. Pass it explicitly and the ribbon stays accurate:

- run: ./gradlew assembleDebug -PgitBranch=${{ github.head_ref || github.ref_name }}

Without it, CI debug builds simply fall back to the static "DEBUG" ribbon — the build never fails.

Caveats

Two intentional limitations, surfaced upfront.

Adaptive foreground only

branchmark regenerates the adaptive-icon foreground and its anydpi-v26 XML. On minSdk < 26 devices, the legacy square mipmap-<dpi>/ic_launcher.png is shown unstamped — the banner appears only where adaptive icons are supported.

Emoji coverage

The built-in branch types and the default emoji ship as bundled Twemoji SVGs. A custom emoji outside that set renders through a system font as a best-effort fallback, which may be monochrome or a missing-glyph box on a machine without an emoji font.