Enforcing Stability in CI — make stability regressions fail the build

Stability is a property that silently regresses. A new var in a shared data class can disable skipping across dozens of screens, and nothing in the build output complains. Treat stability like binary compatibility: commit a baseline, diff it on every PR, fail the build when the diff goes the wrong way. This skill sets that gate up using the skydoves/compose-stability-analyzer Gradle plugin and points to j-roskopf/ComposeGuard for non-Android multiplatform projects.

When to use this skill

• The team wants a stability service-level objective enforced in CI, not a manual check.
• A PR introduced an unstable parameter and nobody noticed until field reports of dropped frames came in.
• Migrating a large app to strong skipping and need a regression net while refactoring.
• Standardizing stability practice across a monorepo with many feature modules.
• The user mentions stabilityCheck, stabilityDump, baseline drift, ComposeGuard, or "fail the build on stability regression".

When NOT to use this skill

• A single-developer throwaway prototype. The baseline maintenance cost is not worth it.
• Stability has not been diagnosed at all yet. Run ../diagnosing-compose-stability/SKILL.md first to make sure the current state is acceptable; baselining a broken state just locks the brokenness in.
• The conceptual question is "why did the compiler classify X as Y?". Use ../understanding-stability-inference/SKILL.md.

Prerequisites

• Kotlin 2.0+ with the Compose compiler Gradle plugin (org.jetbrains.kotlin.plugin.compose). Strong skipping is default on.
• Gradle 8+.
• A working CI pipeline that already runs ./gradlew assemble or equivalent.
• Compose Compiler reports already understood (read ../diagnosing-compose-stability/SKILL.md first).
• Ability to commit generated files to the repository (the .stability baseline must be checked in).

Workflow

1. Apply the plugin

Add the plugin to the version catalog and apply it to every module that ships UI composables.

toml
# gradle/libs.versions.toml
[versions]
compose-stability-analyzer = "0.7.3"

[plugins]
compose-stability-analyzer = { id = "com.github.skydoves.compose.stability.analyzer", version.ref = "compose-stability-analyzer" }

kotlin
// app/build.gradle.kts (and every UI feature module)
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.compose.stability.analyzer)
}

The plugin must be applied after the Compose compiler plugin so it can read the same compiler output.

2. Configure the DSL block

kotlin
// app/build.gradle.kts
composeStabilityAnalyzer {
    enabled.set(true)

    stabilityValidation {
        enabled.set(true)
        outputDir.set(layout.projectDirectory.dir("stability"))
        failOnStabilityChange.set(true)
        ignoredPackages.set(
            listOf(
                "com.example.preview",     // @Preview-only composables
                "com.example.benchmark",   // microbenchmark fixtures
            )
        )
        ignoredClasses.set(
            listOf(
                "com.example.testing.FakeRepository",
            )
        )
        stabilityConfigurationFiles.add(
            rootProject.layout.projectDirectory.file("stability_config.conf")
        )
    }
}

Key settings:

• outputDir — where .stability baseline files are written. Pick a path inside the module so it is naturally co-located with the source. Do not write to build/; that directory is gitignored and the baseline must be committed.
• failOnStabilityChange — set to true for CI. Locally, developers may toggle this to false for iteration speed, but the committed value must be true.
• ignoredPackages / ignoredClasses — exclude @Preview composables, benchmark fixtures, and test doubles that intentionally violate stability rules.
• stabilityConfigurationFiles — point at the same stability_config.conf the Compose compiler uses, so the plugin's verdict matches the compiler's.

3. Generate the baseline locally

bash
./gradlew :app:stabilityDump
# or, for a specific variant:
./gradlew :app:debugStabilityDump

The plugin writes one .stability file per module per variant under outputDir. Commit them.

bash
git add app/stability/
git commit -m "chore(stability): seed baseline"

A single .stability entry looks like this:

text
@Composable
public fun com.example.CounterDisplay(count: com.example.MainViewModel): kotlin.Unit
  skippable: false
  restartable: true
  params:
    - count: RUNTIME (requires runtime check)

Each entry records the composable signature, skippable / restartable flags, and the per-parameter stability classification. The diff format is line-stable across runs, so PR reviewers see a meaningful change set.

4. Wire stabilityCheck into CI

Add a Gradle task invocation to the same job that compiles. Earlier signal beats a separate stage.

yaml
# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17
      - uses: gradle/actions/setup-gradle@v4
      - name: Assemble and check stability
        run: ./gradlew assemble :app:stabilityCheck
      - name: Upload stability diff on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: stability-diff
          path: app/build/reports/stability/

stabilityCheck reads the committed baseline, regenerates the current snapshot in build/, diffs them, and fails the task if any composable became less skippable or any class became less stable. The PR check turns red and the developer sees exactly which composable regressed and why.

5. Handle a regression

When stabilityCheck fails, the task output names the regressed composables and the new unstable parameter or class. The developer has two valid responses:

• Fix the regression. Stabilize the offending type (var → val, List → ImmutableList, Flow parameter → collectAsStateWithLifecycle upstream). Re-run :stabilityDump locally to confirm the baseline is unchanged, then push.
• Update the baseline with justification. Some regressions are acceptable (e.g. an interop boundary that must accept a Java POJO). Run :stabilityDump to update the baseline, commit it, and add a note in the PR description explaining why the regression is intentional. Code review enforces the justification — the diff is plain text and reviewable.

Treat baseline updates the same way the team treats binary-compatibility baseline updates: visible in code review, requires explanation.

6. Tune ignores conservatively

ignoredPackages and ignoredClasses exist for legitimate exemptions: previews, benchmarks, test doubles, generated code. Do not use them to silence regressions in production code. Every ignore entry needs a comment explaining why; reviewers should reject ignore additions that lack a rationale.

kotlin
// RIGHT
ignoredPackages.set(
    listOf(
        "com.example.preview",  // @Preview composables intentionally use mutable state for tooling
        "com.example.benchmark" // microbenchmark fixtures need fresh allocations per iteration
    )
)

kotlin
// WRONG
ignoredPackages.set(listOf("com.example.feature.cart"))
// WRONG because: silencing an entire production package hides real regressions in cart.
// The team will rediscover the lost skipping as field jank weeks later.

7. Alternate: ComposeGuard for multiplatform / non-Android

If the project is Compose Multiplatform (desktop, iOS via KMP) or otherwise outside the Android Gradle plugin's reach, use j-roskopf/ComposeGuard. It implements the same idea (commit a baseline, diff in CI, fail on regression) and exposes <variant>ComposeCompilerGenerate and <variant>ComposeCompilerCheck tasks. Wire it the same way as stabilityDump / stabilityCheck above. The skydoves plugin is the primary recommendation for Android-only projects because it integrates with @TraceRecomposition for runtime correlation.

Patterns

Pattern: commit the baseline, diff it in PRs

text
# RIGHT
app/stability/
  app-debug.stability   <-- committed
  app-release.stability <-- committed

# CI runs:
./gradlew :app:stabilityCheck   # diffs current vs committed baseline; fails on regression

text
# WRONG
app/build/stability/    <-- in build/, gitignored, never committed
# WRONG because: every CI run starts from a fresh build/, the baseline does not exist,
# stabilityCheck either no-ops or always passes. The gate is theater.

Pattern: failOnStabilityChange in CI, optional locally

kotlin
// RIGHT — committed default
composeStabilityAnalyzer {
    stabilityValidation {
        failOnStabilityChange.set(true)
    }
}

kotlin
// WRONG — committed default
composeStabilityAnalyzer {
    stabilityValidation {
        failOnStabilityChange.set(false)
    }
}
// WRONG because: turns the gate into an informational warning. Developers learn to ignore
// the warning. Stability regresses anyway. Set true and let CI block the merge.

Local override is fine via a Gradle property the developer can pass:

kotlin
failOnStabilityChange.set(
    providers.gradleProperty("composeStabilityStrict").orNull?.toBoolean() ?: true
)

bash
# Local fast iteration — opt out explicitly per invocation
./gradlew :app:stabilityCheck -PcomposeStabilityStrict=false

Pattern: run stabilityCheck in the assemble job, not a separate one

yaml
# RIGHT — earlier signal, single workflow run
- run: ./gradlew assemble :app:stabilityCheck

yaml
# WRONG — separate jobs split signal
jobs:
  assemble:
    steps: [./gradlew assemble]
  stability:
    needs: assemble
    steps: [./gradlew :app:stabilityCheck]

text
# WRONG because: the stability job re-resolves dependencies and re-runs Compose compilation
# from scratch, doubling CI time and delaying the failure signal. Same job, single Gradle daemon.

Pattern: pair the CI gate with @TraceRecomposition at runtime

The plugin proves a class is classified stable. It does not prove the running app actually recomposes less. Pair the CI gate with runtime tracing (see ../../measurement/tracing-recompositions-at-runtime/SKILL.md) so the team has both signals: compile-time classification stability and runtime recomposition counts. A green CI gate with rising recomposition counts means a runtime-only invalidation source (e.g. a misplaced mutableStateOf read) that classification cannot catch.

Mandatory rules

• MUST commit the .stability baseline file(s) to version control. A baseline that lives in build/ is not a baseline.
• MUST set failOnStabilityChange.set(true) in the committed Gradle config so CI blocks merges on regression. Local opt-out via a Gradle property is acceptable; committing false is not.
• MUST NOT add a package or class to ignoredPackages / ignoredClasses without a one-line comment explaining why. Unjustified ignores are how stability silently rots back in.
• MUST NOT baseline a known-bad starting state and call the work done. Run ../diagnosing-compose-stability/SKILL.md and ../stabilizing-compose-types/SKILL.md first; baseline only what the team is willing to defend.
• MUST apply the plugin to every UI module, not just :app. A regression in a feature module is invisible to a :app-only check until the feature is wired into the main graph.
• PREFERRED: run :stabilityCheck in the same CI job as compile, behind assemble. Earlier signal, one Gradle daemon, half the wall-clock time.
• PREFERRED: when ComposeGuard is the better fit (KMP/desktop/iOS), use it — but match the workflow shape exactly: commit the baseline, fail the build on diff, justify ignores in code review.
• PREFERRED: point stabilityConfigurationFiles at the same stability_config.conf the Compose compiler reads, so the plugin and the compiler agree on classifications.

Stability is a contract, not a magic spell — and the CI gate is the contract enforcer. Skippability is a diagnostic, not a KPI: the goal is "no regressions from the baseline the team agreed on", not "100% skippable".

Verification

• ] composeStabilityAnalyzer plugin block present in every UI module's build.gradle.kts.
• ] app/stability/ (or the configured outputDir) is committed to the repo and contains at least one .stability file per shipping variant.
• ] failOnStabilityChange.set(true) is the committed default.
• ] CI workflow runs ./gradlew :app:stabilityCheck (or the equivalent module path) on every pull request.
• ] Test the gate: temporarily change a val to var in a shared data class on a throwaway branch, push, and confirm the PR check turns red with the regressed composable named in the failure output. Revert the test change.
• ] Every entry in ignoredPackages and ignoredClasses has a comment explaining why it is exempt.
• ] When a developer runs ./gradlew :app:stabilityDump locally, the only changes (if any) are in the .stability files and are reviewable as plain text.

References

• skydoves/compose-stability-analyzer — https://github.com/skydoves/compose-stability-analyzer
• skydoves, "Optimize App Performance by Mastering Stability" — https://medium.com/proandroiddev/optimize-app-performance-by-mastering-stability-in-jetpack-compose-69f40a8c785d
• Compose stability overview — https://developer.android.com/develop/ui/compose/performance/stability
• Strong Skipping — https://developer.android.com/develop/ui/compose/performance/stability/strongskipping
• Ben Trengrove, "New ways of optimizing stability in Jetpack Compose" — https://medium.com/androiddevelopers/new-ways-of-optimizing-stability-in-jetpack-compose-038106c283cc
• Chris Banes, "Composable metrics" — https://chrisbanes.me/posts/composable-metrics/
• Compose Compiler release notes — https://developer.android.com/jetpack/androidx/releases/compose-compiler
• ComposeGuard (alternative for KMP) — https://github.com/j-roskopf/ComposeGuard
• skydoves/compose-stability-inference — https://github.com/skydoves/compose-stability-inference

For runtime correlation of CI-green stability with actual recomposition counts, see ../../measurement/tracing-recompositions-at-runtime/SKILL.md. For the conceptual classification model that determines what stabilityCheck is checking, see ../understanding-stability-inference/SKILL.md. For the upstream type fixes that resolve regressions surfaced by the gate, see ../stabilizing-compose-types/SKILL.md.