From b8053d5c420ecdd72ec824a3fbac80ff3491668c Mon Sep 17 00:00:00 2001 From: Mas Azalya Date: Mon, 2 Nov 2026 14:14:49 +0800 Subject: [PATCH 1/3] Add a release workflow for ShimmerCapture Automates the Confluence procedure "ShimmerCapture Android Release (shimmerServiceExample)": builds the shimmerServiceExample release APK, signed with the upload keystore from repository secrets the same way Android Studio's Generate Signed APK does, tags ShimmerCapture_v and creates the GitHub pre-release with the APK. With google_play ticked it also uploads the APK to Play's Production track as a draft, to be sent for review in Play Console. The version stays committed in build.gradle: the workflow refuses a version already tagged, a versionCode no higher than the last release's, and a build not set to APP_RELEASE_TYPE.PUBLIC. PRs that change the workflow dry-run it unsigned. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release-shimmercapture.yml | 345 +++++++++++++++++++ 1 file changed, 345 insertions(+) create mode 100644 .github/workflows/release-shimmercapture.yml diff --git a/.github/workflows/release-shimmercapture.yml b/.github/workflows/release-shimmercapture.yml new file mode 100644 index 0000000..7fad20f --- /dev/null +++ b/.github/workflows/release-shimmercapture.yml @@ -0,0 +1,345 @@ +# One-click release of the ShimmerCapture app (the shimmerServiceExample module): a signed APK on a +# GitHub pre-release, and optionally a draft release in Google Play. It automates the Confluence page +# "ShimmerCapture Android Release (shimmerServiceExample)", which did the same by hand in Android +# Studio. +# +# How to release +# 1. In a PR, as before, raise versionCode and versionName in shimmerServiceExample/build.gradle, +# and leave MainActivity.appReleaseType at PUBLIC. Merge it. +# 2. Actions -> "Release ShimmerCapture" -> Run workflow (on master). The version is the +# versionName in build.gradle, tagged ShimmerCapture_v. +# 3. With google_play ticked, the APK goes to Play Console's Production track as a draft. In Play +# Console, open that release, check it, and "Send changes for review", as on the Confluence page. +# +# Unlike the Android API's release.yml, the version is committed rather than typed: Play needs a +# versionCode higher than every one before it, and build.gradle is the only record of the last one. +# +# One run does, in order, and creates nothing public until the APK has built and is signed: +# build reads the version; fails if it is already tagged, if versionCode did not go up since the +# last ShimmerCapture release, or if the app is not set to PUBLIC; builds the signed +# release APK. Read-only (no keystore without it): it also runs, unsigned, on PRs. +# release tags ShimmerCapture_v on the commit it built and creates the GitHub +# pre-release with the APK and notes since the previous ShimmerCapture release. +# Pre-release, so the Android API release stays "Latest", as before. +# play google_play only: uploads the same APK to Play's Production track as a draft. +# +# If a later job fails, "Re-run failed jobs" re-runs just that job. +# +# Secrets (repository Settings -> Secrets and variables -> Actions) +# SHIMMERCAPTURE_KEYSTORE_BASE64 the upload keystore (.jks) used in Android Studio, base64: +# [Convert]::ToBase64String([IO.File]::ReadAllBytes("x.jks")) +# SHIMMERCAPTURE_KEYSTORE_PASSWORD its store password +# SHIMMERCAPTURE_KEY_ALIAS the key alias +# SHIMMERCAPTURE_KEY_PASSWORD the key password +# GOOGLE_PLAY_SERVICE_ACCOUNT_JSON google_play only: JSON key of a Google Cloud service account +# invited in Play Console (Users and permissions) with "Release +# to production" on ShimmerCapture +# A real release refuses to run without the keystore. A dry run builds unsigned if it is missing, +# and a PR run always builds unsigned. +# +# The driver is read from Shimmer-Java-Android-API's GitHub Packages, as in release.yml: this repo's +# GITHUB_TOKEN, or PACKAGES_READ_TOKEN if that is ever refused. +# +# dry_run builds the signed APK (unsigned without the keystore) and keeps it as a workflow artifact, +# from any branch, and publishes nothing. The workflow also dry-runs on any PR that changes this file. + +name: Release ShimmerCapture + +on: + workflow_dispatch: + inputs: + google_play: + description: 'Also upload to Google Play Production as a draft, to send for review in Play Console' + type: boolean + default: false + whats_new: + description: 'Google Play release notes (en-US, 500 characters max). Blank = "Bug fixes and improvements."' + type: string + required: false + dry_run: + description: 'Build only; publish nothing' + type: boolean + default: false + pull_request: + paths: + - '.github/workflows/release-shimmercapture.yml' + +concurrency: + group: release-shimmercapture + cancel-in-progress: false + +defaults: + run: + working-directory: ShimmerAndroidInstrumentDriver + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 30 # a hung Gradle daemon otherwise holds the runner for 6 hours + permissions: + contents: read + packages: read + env: + DRY_RUN: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run }} + # Read by the repositories in the root build.gradle to resolve the driver. + USERNAME: ${{ github.actor }} + TOKEN: ${{ secrets.PACKAGES_READ_TOKEN || github.token }} + outputs: + version: ${{ steps.version.outputs.version }} + version_code: ${{ steps.version.outputs.version_code }} + tag: ${{ steps.version.outputs.tag }} + previous_tag: ${{ steps.version.outputs.previous_tag }} + driver: ${{ steps.version.outputs.driver }} + apk: ${{ steps.collect.outputs.apk }} + steps: + - name: Release from master only + if: env.DRY_RUN != 'true' && github.ref != 'refs/heads/master' + working-directory: . + run: | + echo "::error::A release must run on master, not ${GITHUB_REF_NAME}. Tick dry_run to try another branch." + exit 1 + + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + fetch-depth: 0 # tags, to refuse a version that is already released + # Keep the token out of .git/config, where the Gradle build could read it. + persist-credentials: false + + - name: Check the version and the release type + id: version + env: + GH_TOKEN: ${{ github.token }} + run: | + gradle_file=shimmerServiceExample/build.gradle + VERSION=$(sed -nE 's/^\s*versionName\s+"([^"]+)".*/\1/p' "$gradle_file") + VERSION_CODE=$(sed -nE 's/^\s*versionCode\s+([0-9]+).*/\1/p' "$gradle_file") + if [ -z "$VERSION" ] || [ -z "$VERSION_CODE" ]; then + echo "::error::Cannot read versionName and versionCode from $gradle_file." + exit 1 + fi + TAG="ShimmerCapture_v$VERSION" + + PREVIOUS_TAG=$(gh release list --repo "$GITHUB_REPOSITORY" --limit 200 --json tagName,createdAt \ + --jq '[.[] | select(.tagName | startswith("ShimmerCapture_v"))] | sort_by(.createdAt) | last | .tagName // ""') + + fail() { + if [ "$DRY_RUN" = true ]; then + echo "::warning::$1 A real release would stop here. Dry run continues." + else + echo "::error::$1" + exit 1 + fi + } + + if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then + fail "$VERSION is already released as $TAG. Raise versionName and versionCode in $gradle_file first." + fi + # Play refuses a versionCode it has seen, so check it went up since the last release. + if [ -n "$PREVIOUS_TAG" ]; then + previous_code=$(git show "refs/tags/$PREVIOUS_TAG:ShimmerAndroidInstrumentDriver/$gradle_file" 2>/dev/null \ + | sed -nE 's/^\s*versionCode\s+([0-9]+).*/\1/p') + if [ -n "$previous_code" ] && [ "$VERSION_CODE" -le "$previous_code" ]; then + fail "versionCode $VERSION_CODE is not higher than $previous_code in $PREVIOUS_TAG. Raise it in $gradle_file." + fi + fi + # The Confluence procedure's first step: a Play release must be the PUBLIC build. + release_type=$(sed -nE 's/.*appReleaseType\s*=\s*APP_RELEASE_TYPE\.([A-Z_]+).*/\1/p' \ + shimmerServiceExample/src/main/java/com/shimmerresearch/shimmercapture/MainActivity.java) + if [ "$release_type" != PUBLIC ]; then + fail "MainActivity.appReleaseType is ${release_type:-not found}, not PUBLIC." + fi + + DRIVER=$(sed -nE "s/.*findProperty\('driverVersion'\) \?: '([^']+)'.*/\1/p" build.gradle) + { + echo "version=$VERSION" + echo "version_code=$VERSION_CODE" + echo "tag=$TAG" + echo "previous_tag=$PREVIOUS_TAG" + echo "driver=$DRIVER" + } >> "$GITHUB_OUTPUT" + echo "Releasing ShimmerCapture $VERSION (versionCode $VERSION_CODE) as $TAG against driver ${DRIVER:-unknown}; notes since ${PREVIOUS_TAG:-the first commit}" + + # Decoded before building so a missing keystore fails in seconds. The keystore is written + # outside the checkout, and the step that uses it deletes it. Never on a PR: the build runs the + # PR's own Gradle scripts, which could read it. + - name: Set up the signing keystore + id: keystore + env: + KEYSTORE_BASE64: ${{ github.event_name == 'workflow_dispatch' && secrets.SHIMMERCAPTURE_KEYSTORE_BASE64 || '' }} + run: | + if [ -z "$KEYSTORE_BASE64" ]; then + if [ "$DRY_RUN" = true ]; then + echo "::warning::No SHIMMERCAPTURE_KEYSTORE_BASE64 secret, so this dry run builds an unsigned APK." + echo "signed=false" >> "$GITHUB_OUTPUT" + exit 0 + fi + echo "::error::No SHIMMERCAPTURE_KEYSTORE_BASE64 secret. See the secrets list at the top of this workflow." + exit 1 + fi + keystore="$RUNNER_TEMP/shimmercapture-upload.jks" + printf '%s' "$KEYSTORE_BASE64" | base64 -d > "$keystore" + echo "signed=true" >> "$GITHUB_OUTPUT" + echo "path=$keystore" >> "$GITHUB_OUTPUT" + + # AGP 8 needs JDK 17. + - name: Set up JDK 17 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1 + with: + java-version: '17' + distribution: 'temurin' + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@ec92e829475ac0c2315ea8f9eced72db85bb337a # v3.0.0 + + # The android.injected.signing.* properties are what Android Studio's "Generate Signed App + # Bundle / APK" passes, so this signs exactly as the manual procedure did, with no signing + # config in build.gradle. Actions masks the secrets in the log. gradle.properties is gitignored + # here, so android.useAndroidX and the daemon heap are passed on the command line, as in ci.yml. + - name: Build the release APK + env: + SIGNED: ${{ steps.keystore.outputs.signed }} + KEYSTORE: ${{ steps.keystore.outputs.path }} + KEYSTORE_PASSWORD: ${{ secrets.SHIMMERCAPTURE_KEYSTORE_PASSWORD }} + KEY_ALIAS: ${{ secrets.SHIMMERCAPTURE_KEY_ALIAS }} + KEY_PASSWORD: ${{ secrets.SHIMMERCAPTURE_KEY_PASSWORD }} + run: | + signing=() + if [ "$SIGNED" = true ]; then + trap 'rm -f "$KEYSTORE"' EXIT + signing=( + -Pandroid.injected.signing.store.file="$KEYSTORE" + -Pandroid.injected.signing.store.password="$KEYSTORE_PASSWORD" + -Pandroid.injected.signing.key.alias="$KEY_ALIAS" + -Pandroid.injected.signing.key.password="$KEY_PASSWORD" + ) + fi + ./gradlew :shimmerServiceExample:assembleRelease -Pandroid.useAndroidX=true "${signing[@]}" \ + -Dorg.gradle.jvmargs="-Xmx4g -XX:MaxMetaspaceSize=1g" + + - name: Collect and check the APK + id: collect + env: + VERSION: ${{ steps.version.outputs.version }} + VERSION_CODE: ${{ steps.version.outputs.version_code }} + SIGNED: ${{ steps.keystore.outputs.signed }} + run: | + out=shimmerServiceExample/build/outputs/apk/release + ls -l "$out" + if [ "$SIGNED" = true ]; then + built="$out/shimmerServiceExample-release.apk" + name="ShimmerCapture_v$VERSION.apk" + else + built="$out/shimmerServiceExample-release-unsigned.apk" + name="ShimmerCapture_v$VERSION-unsigned.apk" + fi + mkdir -p ../release-assets + cp "$built" "../release-assets/$name" + + build_tools=$(ls -d "$ANDROID_HOME"/build-tools/* | sort -V | tail -1) + badging=$("$build_tools/aapt2" dump badging "../release-assets/$name" | head -1) + echo "$badging" + if ! grep -q "versionCode='$VERSION_CODE'" <<<"$badging" || ! grep -q "versionName='$VERSION'" <<<"$badging"; then + echo "::error::The APK does not carry versionName $VERSION and versionCode $VERSION_CODE." + exit 1 + fi + if [ "$SIGNED" = true ]; then + "$build_tools/apksigner" verify --print-certs "../release-assets/$name" + fi + echo "apk=$name" >> "$GITHUB_OUTPUT" + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: shimmercapture-apk + path: release-assets/ + if-no-files-found: error + + release: + needs: build + if: github.event_name == 'workflow_dispatch' && !inputs.dry_run + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write # create the tag and the release + env: + GH_TOKEN: ${{ github.token }} + VERSION: ${{ needs.build.outputs.version }} + VERSION_CODE: ${{ needs.build.outputs.version_code }} + TAG: ${{ needs.build.outputs.tag }} + PREVIOUS_TAG: ${{ needs.build.outputs.previous_tag }} + DRIVER: ${{ needs.build.outputs.driver }} + steps: + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: shimmercapture-apk + path: release-assets + + # Generated notes cover every PR since the last ShimmerCapture tag, not only the app's: the app + # ships the library and the driver too. + - name: Create the tag and GitHub pre-release + working-directory: . + run: | + args=(-f tag_name="$TAG" -f target_commitish="$GITHUB_SHA") + if [ -n "$PREVIOUS_TAG" ]; then args+=(-f previous_tag_name="$PREVIOUS_TAG"); fi + { + echo "ShimmerCapture $VERSION (versionCode $VERSION_CODE), built from \`shimmerServiceExample\` against Shimmer Java API driver ${DRIVER:-(unknown)}." + echo + gh api "repos/$GITHUB_REPOSITORY/releases/generate-notes" "${args[@]}" --jq .body + } > notes.md + gh release create "$TAG" release-assets/* \ + --repo "$GITHUB_REPOSITORY" \ + --target "$GITHUB_SHA" \ + --title "$TAG" \ + --notes-file notes.md \ + --prerelease + { + echo "### Released ShimmerCapture $VERSION" + echo "- Release: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$TAG" + echo "- versionCode $VERSION_CODE, driver ${DRIVER:-unknown}" + } >> "$GITHUB_STEP_SUMMARY" + + play: + needs: [build, release] + if: github.event_name == 'workflow_dispatch' && !inputs.dry_run && inputs.google_play + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: {} + steps: + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: shimmercapture-apk + path: release-assets + + - name: Write the release notes + working-directory: . + env: + WHATS_NEW: ${{ inputs.whats_new }} + HAS_ACCOUNT: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON != '' }} + run: | + if [ "$HAS_ACCOUNT" != true ]; then + echo "::error::No GOOGLE_PLAY_SERVICE_ACCOUNT_JSON secret. The GitHub release is done; upload $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases to Play Console by hand, or add the secret and re-run this job." + exit 1 + fi + mkdir -p whatsnew + printf '%s\n' "${WHATS_NEW:-Bug fixes and improvements.}" > whatsnew/whatsnew-en-US + if [ "$(wc -m < whatsnew/whatsnew-en-US)" -gt 500 ]; then + echo "::error::Google Play allows 500 characters of release notes." + exit 1 + fi + + # A draft, so a person still checks the release in Play Console and sends it for review, as in + # the manual procedure. + - name: Upload to Google Play (Production, draft) + uses: r0adkll/upload-google-play@e738b9dd8f2476ea806d921b64aacd24f34515a5 # v1.1.5 + with: + serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }} + packageName: com.shimmersensing.shimmerconnect + releaseFiles: release-assets/${{ needs.build.outputs.apk }} + releaseName: ${{ needs.build.outputs.version }} + track: production + status: draft + whatsNewDirectory: whatsnew + + - name: Summary + working-directory: . + run: | + echo "### Uploaded to Google Play as a draft on Production. In Play Console: Test and release -> Production -> review the release -> Send changes for review." >> "$GITHUB_STEP_SUMMARY" From e6e66f99b122fc38fc533c4f58053ddcf8db021b Mon Sep 17 00:00:00 2001 From: Mas Azalya Date: Mon, 2 Nov 2026 14:14:49 +0800 Subject: [PATCH 2/3] ShimmerCapture 1.3.4 (versionCode 35) Co-Authored-By: Claude Opus 5.5 --- .../shimmerServiceExample/build.gradle | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle index 59c9a7f..efba3d8 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle @@ -8,8 +8,8 @@ android { applicationId "com.shimmersensing.shimmerconnect" minSdkVersion 21 targetSdkVersion 35 - versionCode 34 - versionName "1.3.3" + versionCode 35 + versionName "1.3.4" multiDexEnabled true testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" From e622b9772ae0f985e811d49c7b816ec091547533 Mon Sep 17 00:00:00 2001 From: Mas Azalya Date: Mon, 2 Nov 2026 15:11:56 +0800 Subject: [PATCH 3/3] DEV-1395: Document the ShimmerCapture release, from uprev to Play review RELEASING.md walks through a release: the uprev PR, an optional signed dry run, the workflow run, sending the draft for review in Play Console, failures and their fixes, and the secrets. Linked from the module README, the workflow header and AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release-shimmercapture.yml | 2 +- AGENTS.md | 5 +- .../shimmerServiceExample/README.md | 4 + .../shimmerServiceExample/RELEASING.md | 165 ++++++++++++++++++ 4 files changed, 174 insertions(+), 2 deletions(-) create mode 100644 ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md diff --git a/.github/workflows/release-shimmercapture.yml b/.github/workflows/release-shimmercapture.yml index 7fad20f..187b9fb 100644 --- a/.github/workflows/release-shimmercapture.yml +++ b/.github/workflows/release-shimmercapture.yml @@ -3,7 +3,7 @@ # "ShimmerCapture Android Release (shimmerServiceExample)", which did the same by hand in Android # Studio. # -# How to release +# How to release (the full guide is ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md) # 1. In a PR, as before, raise versionCode and versionName in shimmerServiceExample/build.gradle, # and leave MainActivity.appReleaseType at PUBLIC. Merge it. # 2. Actions -> "Release ShimmerCapture" -> Run workflow (on master). The version is the diff --git a/AGENTS.md b/AGENTS.md index 232d52b..4627fec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,7 +134,10 @@ rather than queueing. `.github/workflows/ci.yml` runs on every PR into master and every push to it. It builds the library and every example (`assembleDebug`), then runs the library's unit tests, against the default driver. No check is required to merge yet, so look at the result. `release.yml` is the dispatch-only Release -Android API workflow; it dry-runs on any PR that changes it. +Android API workflow; it dry-runs on any PR that changes it. `release-shimmercapture.yml` does the +same for the ShimmerCapture app (`shimmerServiceExample`): a signed APK, a GitHub pre-release and a +draft Google Play release. Its version comes from that module's `build.gradle`, so each release +starts with an uprev PR; `shimmerServiceExample/RELEASING.md` is the step-by-step guide. ## Modules diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/README.md b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/README.md index f1f7532..ce09eda 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/README.md +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/README.md @@ -11,3 +11,7 @@ This ShimmerSeriviceExample allows user to - Erase data in Verisense device - Disable logging in Verisense device - Data sync Verisense device + +## Releasing + +This app is published to Google Play as ShimmerCapture. [RELEASING.md](RELEASING.md) has every step, from raising the version to sending the release for review. diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md new file mode 100644 index 0000000..2b3200f --- /dev/null +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md @@ -0,0 +1,165 @@ +# Releasing ShimmerCapture + +ShimmerCapture is this module, `shimmerServiceExample` (Play package +`com.shimmersensing.shimmerconnect`). A release is: + +1. an **uprev PR** that raises the version in `build.gradle`, then +2. one run of the **Release ShimmerCapture** workflow + ([`.github/workflows/release-shimmercapture.yml`](../../.github/workflows/release-shimmercapture.yml)), + which builds and signs the APK, creates the GitHub pre-release and, if asked, puts a draft release + in Google Play, then +3. **sending the draft for review** in Play Console, by hand. + +The workflow never changes the version itself. It reads it from `build.gradle` on `master`, so +step 1 is not optional: without it, the run stops at its first check. + +## 1. Uprev the version + +Start a branch from `master`, named for the Jira ticket (e.g. `DEV-1234_shimmercapture_v1.3.4`). + +In [`build.gradle`](build.gradle), raise both values in `defaultConfig`: + +```groovy +versionCode 35 // +1 on the last release. Google Play rejects a code it has seen before +versionName "1.3.4" // the version users see; also the tag, ShimmerCapture_v1.3.4 +``` + +- `versionCode` goes up by **1** each release, whatever the change. +- `versionName` normally goes up by one patch (1.3.3 → 1.3.4). Raise the minor (1.3.x → 1.4.0) for + a larger change. +- The last released values are in the newest + [`ShimmerCapture_v…` release](https://github.com/ShimmerResearch/ShimmerAndroidAPI/releases)'s + notes, and in `build.gradle` at its tag. + +Check that `MainActivity` is the public build: + +```java +public static APP_RELEASE_TYPE appReleaseType = APP_RELEASE_TYPE.PUBLIC; +``` + +`INTERNAL` and `TESTING` are for builds that do not go to Google Play. The workflow refuses to +release anything else. + +Then, as before the workflow existed: + +1. Sync Gradle in Android Studio, **Clean Project**, run the app on a device and check that it + connects, configures, streams and plots. +2. Commit (`ShimmerCapture 1.3.4 (versionCode 35)`), push, and open a PR into `master`. +3. Wait for CI ("Build and test") to pass, get it reviewed, and merge. + +## 2. Optional: a dry run + +To check the signing and the version before publishing anything: + +1. **Actions** → **Release ShimmerCapture** → **Run workflow**. +2. Branch `master`, tick **dry_run**, then **Run workflow**. + +A dry run does everything up to the signed APK and stops. Open the run to check: + +- **build** → *Collect and check the APK* prints the APK's `versionCode` and `versionName`, and + `Signer #1 certificate SHA-256 digest`. That digest must match Play Console → ShimmerCapture → + *Test and release* → *App integrity* → **Upload key certificate**. If it doesn't, Play rejects the + upload. +- The APK itself is on the run page under **Artifacts** (`shimmercapture-apk`), to install on a test + device. + +A dry run can be started from any branch, so it is also the way to try an uprev before merging it. + +## 3. Run the release + +1. **Actions** → **Release ShimmerCapture** → **Run workflow**. +2. Fill in: + + | Field | Value | + |---|---| + | Use workflow from | `master` (a release refuses any other branch) | + | google_play | ticked, to put a draft release in Google Play. Unticked = GitHub release only | + | whats_new | the Play release notes, in English, at most 500 characters. Blank = "Bug fixes and improvements." Copying the previous release's notes and editing them works well | + | dry_run | unticked | + +3. **Run workflow**, and wait for the three jobs, about 10 minutes: + - **build**: checks the version, then builds and signs the APK. + - **release**: tags `ShimmerCapture_v` and creates the GitHub **pre-release**, with + the APK and notes listing every PR since the last ShimmerCapture release. It is a pre-release + so the Android API release stays *Latest* on the releases page. + - **play**: uploads the APK to Play's **Production** track as a **draft**. Skipped when + google_play is unticked. + +The run's summary page links the new release. + +## 4. Send it for review in Play Console + +The workflow leaves the Play release as a draft on purpose, so a person checks it before it goes +out. + +1. [Play Console](https://play.google.com/console) → **ShimmerCapture** → **Test and release** → + **Production**. +2. Open the draft release. It is named after the version, e.g. `1.3.4`. Check the APK's version + code and the release notes, then **Next**. +3. Ignore any page you have no changes for, then **Save** → **Go to Publishing overview**. +4. **Send changes for review**. + +Google's review usually takes from a few hours to a few days. Play Console emails the account when +the release is live. + +Not uploading through the workflow? Download the APK from the GitHub release, and in step 2 use +**Create new release** → **Upload** instead. + +## 5. Afterwards + +- Move the ticket on in Jira. +- If the release changes what the app does, update this module's [README](README.md). + +## When a run fails + +**Re-run failed jobs** on the run page re-runs only what failed, so a GitHub release that was +already created is not created twice. + +| Message | Cause and fix | +|---|---| +| `A release must run on master` | Started from another branch. Pick `master`, or tick dry_run | +| `… is already released as ShimmerCapture_v…` | No uprev was merged. Do step 1 | +| `versionCode N is not higher than M` | `versionName` was raised but `versionCode` wasn't. Raise it in a new uprev PR | +| `MainActivity.appReleaseType is …, not PUBLIC` | Set it back to `PUBLIC` in a PR | +| `No SHIMMERCAPTURE_KEYSTORE_BASE64 secret` | The signing secrets are missing. See *Secrets* below | +| `The APK does not carry versionName …` | The build didn't pick up `build.gradle`'s values. Check for a version override in Gradle files | +| **play**: `No GOOGLE_PLAY_SERVICE_ACCOUNT_JSON secret` | The Play secret is missing. The GitHub release is done; upload by hand (step 4), or add the secret and re-run the job | +| **play**: `The caller does not have permission` | The service account lacks access to ShimmerCapture in Play Console, or was just added: new permissions can take a day. Re-run the play job later | +| **play**: `APK specifies a version code that has already been used` | That `versionCode` reached Play before, e.g. by hand. Uprev again | + +## Secrets + +Set once, under the repository's **Settings** → **Secrets and variables** → **Actions**. Setting +them needs admin rights on the repo. Values cannot be read back, so keep the originals in the team's +password store. + +| Secret | What it is | +|---|---| +| `SHIMMERCAPTURE_KEYSTORE_BASE64` | The upload keystore, base64-encoded | +| `SHIMMERCAPTURE_KEYSTORE_PASSWORD` | Its store password | +| `SHIMMERCAPTURE_KEY_ALIAS` | The key's alias (`keytool -list -keystore ` shows it) | +| `SHIMMERCAPTURE_KEY_PASSWORD` | The key's password; often the same as the store password | +| `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` | JSON key of a Google Cloud service account that Play Console's *Users and permissions* gives *Release to production*, *Release apps to testing tracks* and *View app information* on ShimmerCapture. Only the play job needs it | + +To replace the keystore secret, from PowerShell: + +```powershell +[Convert]::ToBase64String([IO.File]::ReadAllBytes("")) | gh secret set SHIMMERCAPTURE_KEYSTORE_BASE64 --repo ShimmerResearch/ShimmerAndroidAPI +``` + +Run `gh secret set --repo ShimmerResearch/ShimmerAndroidAPI` with no value for the passwords: +it asks for them without echoing them. + +For the Play secret, create a JSON key for the service account in Google Cloud, store it, then +delete the file: + +```powershell +Get-Content -Raw | gh secret set GOOGLE_PLAY_SERVICE_ACCOUNT_JSON --repo ShimmerResearch/ShimmerAndroidAPI +``` + +## Building a release by hand + +If the workflow is unavailable, Android Studio still does the same job: **Build** → **Generate +Signed App Bundle / APK** → **APK** → module `shimmerServiceExample`, the upload keystore, build +variant **release**. The APK lands in `shimmerServiceExample/release/`. Do the uprev (step 1) first +all the same, then upload as in step 4.