Enforcing Stability In CI

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.

# 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" }

// 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

// 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

./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.

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

A single .stability entry looks like this:

@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.

# .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.

// 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
    )
)

// 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

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

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

# 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

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

// 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:

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

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