Compose Preview CI

Compose Preview — CI setup

Wiring the compose-preview CI surface into a repository: a compose-preview/main baselines branch, sticky before/after diff comments on pull requests, and the choices that decide whether one workflow is enough or you need two.

This skill is about standing the pipeline up and keeping it working. For reading the diffs it produces — reviewing a UI PR, triaging a flaky preview — see the compose-preview-review skill. For driving the renderer by hand, see compose-preview.

Source

Maintained at github.com/yschimke/skills under skills/compose-preview-ci/. The composite actions described here ship from yschimke/compose-ai-tools; the canonical, always-current input reference is that repo's .github/actions/apply/README.md. When this skill and that README disagree, the README wins — check it before telling a user an input doesn't exist.

Decide the shape first

Everything is one composite action, apply. What differs is how many jobs and workflows you wrap around it.

The fork question is the one to ask first, because it is the only one that changes the file layout rather than a few inputs — and it is the one that silently produces a half-working setup if you get it wrong. A single-job workflow on a repo that takes fork PRs doesn't fail loudly; it just never comments on the contributions from outside, because on a pull_request event from a fork GITHUB_TOKEN is read-only for every scope regardless of the permissions: block.

Ask the user, or infer it: a private repo with no outside contributors is safely single-job. Anything public should assume forks.

What the pipeline produces

Four pipelines run off one action:

The baseline branches do double duty: each has a generated README.md with inline images, so the branch is a browsable gallery on GitHub as well as the "before" side every PR diffs against.

On PRs the same action renders, compares against the baselines, pushes the new renders to compose-preview/pr, and upserts a sticky comment (one per pipeline, keyed by an HTML marker) with the before/after.

a11y and notifications are no-ops unless pointed at a Gradle module via a11y-module / notifications-module. Narrow what runs with only: / skip:.

The single-job workflow

# .github/workflows/compose-preview.yml
name: Compose Preview
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  workflow_dispatch:

permissions:
  contents: write          # baselines push + compose-preview/pr branch
  pull-requests: write     # upserts the sticky PR comment

concurrency:
  group: compose-preview-${{ github.event.pull_request.number || github.ref }}
  # PR runs supersede each other; see the warning below about baseline runs.
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: 17
      - uses: gradle/actions/setup-gradle@v6
      - uses: yschimke/compose-ai-tools/.github/actions/apply@v1.79.0
        with:
          # cli-version defaults to `auto` — leave it alone (see below).
          a11y-module: ''                       # '' = auto-detect all modules
          notifications-module: samples:android # '' = skip the pipeline

mode defaults to auto and is picked from the event: a push to development-branch (default main) → baseline, a pull_request → comment. Override with mode: baseline | comment | skip for one-off workflow_dispatch runs.

Do not cancel-in-progress baseline runs. A cancelled baseline run doesn't just waste a render — it strands the baseline at an older commit, and every subsequent PR then reports the skipped commits' output as its own New/Changed/Removed. Back-to-back merges make that the norm rather than the exception. Gate cancellation on github.event_name == 'pull_request', as above. Queueing is bounded, not unbounded: GitHub keeps at most one pending run per group.

Pin the CLI: leave cli-version on auto

This is the single most common way the action breaks, so it is worth being explicit even though the default is now correct.

Pinning the action ref (apply@v1.79.0) does not pin the CLI. Under the old cli-version: latest, every new compose-ai-tools release auto-installed the newest CLI against a still-pinned Gradle plugin. A CLI newer than the applied plugin cannot discover that older plugin, so the render finds zero preview modules and the pipeline fails repo-wide — on somebody else's release, not on your diff — with a misleading:

✗ no modules have the compose-preview plugin applied
compose pipeline: No preview modules discovered ... skipping.

cli-version: auto (the default) removes this: it reads the plugin version pinned in your checkout — a version-catalog [plugins] entry, or a literal id("…") version "…" in a build script — and installs the CLI at exactly that version. Declare the plugin version once and the CLI follows it:

# gradle/libs.versions.toml
[versions]
composePreviewPlugin = "1.79.0"

[plugins]
composePreview = { id = "ee.schimke.composeai.preview", version.ref = "composePreviewPlugin" }

Renovate bumps that one entry on each release and auto picks it up — no cli-version or catalog-key wiring needed. When no plugin is pinned (the auto-inject / zero-code path, where the CLI injects a matching plugin via --init-script) auto falls back to the project's composePreview.version pin in gradle.properties if there is one, else to latest — both correct there, because the injected plugin always matches the installed CLI.

Other values: latest (opts back into floating), catalog + catalog-key (pin to a dedicated [versions] key), a literal version, source (build from the checkout — internal CI only), none (skip install).

The skew guardrail backs this up independently: after install, apply compares the resolved CLI against the pinned plugin and, when the CLI is newer, fails fast with an actionable message instead of the confusing "no modules" error downstream. skew-check: fail (default) | warn | off. It only acts when it can read a concrete plugin version and both sides are clean releases, so projects deliberately tracking latest with no pinned plugin are never tripped.

Migrating from the legacy actions

The four original composite actions — preview-baselines, preview-comment, a11y-report, notification-previews — were replaced by the unified apply action in v0.11.6. They survive as deprecated shims that forward to apply.

If you find a project still wired to any of them, migrate as part of the next change touching CI. The migration is mechanical and collapses four workflow files — plus their duplicated checkout / Java / Gradle setup — into the single compose-preview.yml above:

Two things to carry over deliberately:

• The shims default cli-version to latest, not auto, because they forward to a pinned released apply that may predate the auto resolver. Once you call apply directly, drop the input and take the auto default.
• a11y-report's baseline-branch / pr-branch inputs were already ignored — apply hardcodes the branch names. Delete them rather than translating them.

When it goes wrong

Reference docs

Related

• compose-preview-review — reading the diffs: reviewing a UI PR, agent-authored PR bodies, triaging flaky previews.
• compose-preview — the renderer itself: CLI, Gradle plugin, capture modes, accessibility checks.