CI Integration¶
In CI, Chameleon Store Studio acts as a quality gate: it validates the assets and reports screenshot changes on every pull request.
storeCi¶
storeCi runs validation and the diff report, prints a summary, and then:
- fails if validation found errors (
ci.failOnValidationErrors, defaulttrue); - fails if images changed, only when
ci.failOnDriftistrue(defaultfalse, since changes in a pull request are usually intentional); - appends the diff summary to the GitHub Actions job summary when
GITHUB_STEP_SUMMARYis set; - posts or updates a sticky pull request comment when
ci.postPrCommentistrue.
Options on the command line:
| Option | Description |
|---|---|
--fail-on-drift / --no-fail-on-drift |
Fail when images changed. |
--fail-on-validation / --no-fail-on-validation |
Fail on validation errors. |
--post-pr-comment |
Post the summary as a pull request comment. |
--pr-number=<n> |
Pull or merge request number, if it can't be detected. |
Boolean options are flags: write --post-pr-comment, not --post-pr-comment=true.
Choosing the base. storeCi runs storeDiff as a dependency, so pass the base with Gradle
properties (command-line options only reach the task you name):
# Render the base branch on this runner (recommended)
./gradlew :app:storeCi -PstoreStudio.diff.renderBase=true -PstoreStudio.diff.against=origin/main
# Or compare with an export of the base branch downloaded from a previous run
./gradlew :app:storeCi -PstoreStudio.diff.baseExport=base-export
Without them, storeCi compares against the committed baseline, if there is one. See
Baselines & Visual Diff.
storeCiCheck is a lifecycle alias for storeCi.
Pull request comments¶
The comment contains the app name, the change counts and a table of modified images. It is updated
in place on every push, identified by ci.commentMarker, which is different for each project: two
apps in the same repository keep two separate comments.
| Platform | Detection | Token |
|---|---|---|
| GitHub Actions | GITHUB_REPOSITORY, GITHUB_EVENT_PATH, GITHUB_REF |
ci.githubToken or GITHUB_TOKEN (needs pull-requests: write) |
| GitLab CI | CI_PROJECT_ID, CI_MERGE_REQUEST_IID, CI_API_V4_URL |
ci.gitlabToken, GITLAB_TOKEN or CI_JOB_TOKEN |
GitHub Actions example¶
This workflow renders both the pull request and its base branch on the same Linux runner and compares
them exactly. Nobody has to record or commit a baseline: once the pull request is merged, the new
main is the base for the next one.
name: Store assets
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
store:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # the base branch must be in the clone
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 17
- uses: gradle/actions/setup-gradle@v6
- name: Validate and compare with the base branch
run: >
./gradlew :app:storeCi --post-pr-comment
-PstoreStudio.diff.renderBase=true
-PstoreStudio.diff.against=origin/${{ github.base_ref }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- uses: actions/upload-artifact@v6
if: always()
with:
name: store-reports
path: |
app/build/store/reports/
app/build/store/export/
Rendering the base costs one extra build of the module, but most of it comes from the Gradle build
cache. setup-gradle writes the cache on main and reads it on pull requests, so add a workflow (or a
job) that builds main on push, for example running ./gradlew :app:storeExport.
Reuse the export of main instead of rendering it
If main uploads its export as an artifact, pull requests can download it and skip the base
render:
# On push to main
- run: ./gradlew :app:storeExport
- uses: actions/upload-artifact@v6
with:
name: store-export-main
path: app/build/store/export/
# On pull requests, before storeCi (needs `actions: read` permission)
- name: Download the export of main
env:
GH_TOKEN: ${{ github.token }}
run: |
run_id=$(gh run list --workflow store.yml --branch main --event push \
--status success --limit 1 --json databaseId --jq '.[0].databaseId')
gh run download "$run_id" --name store-export-main --dir base-export
- run: ./gradlew :app:storeCi --post-pr-comment -PstoreStudio.diff.baseExport=base-export
The export comes from the latest main, which can be newer than the pull request's base. If the
branch is behind main, the diff also shows main's newer changes reversed. Rendering the base
branch always compares against the exact merge base.
Caching¶
- Build cache.
storeRenderis cacheable, so with the Gradle build cache (for examplesetup-gradle's cache, or a remote cache) a pull request that didn't touch any screen restores the images instead of rendering them. Renders affected by machine problems (timeouts, out of memory) are never cached. - Configuration cache. All tasks support it.
- Layoutlib is downloaded once per Gradle user home and reused.
See Performance & Caching for measured times.
Rendering consistency¶
Renders are deterministic on the same machine, but macOS, Windows and Linux can differ by a few
pixels. Compare renders made on the same runner (the workflow above) and keep the default STRICT
comparison. A baseline recorded on a laptop and verified on Linux CI is what PERCEPTUAL mode exists
for, at the cost of missing some small changes. See
What counts as a change.
Uploading with other tools¶
storeExport also writes the listing texts to build/store/export-metadata/, including
play_store/release-notes/whatsnew-<locale> files, so a CI step from another tool can upload them
without Store Studio's publishing:
- run: ./gradlew :app:storeExport
- name: Upload release notes with your Play upload step
uses: your-org/your-play-upload-action@v1
with:
whatsNewDirectory: app/build/store/export-metadata/play_store/release-notes
To publish with Store Studio instead, run a narrow task such as
./gradlew :app:storePublishPlayReleaseNotes --track=production
(see Publishing).