pastello-app

Releasing Pastello

How a version goes from main to GitHub Releases and Google Play (ADR 0016 and 0019). Only maintainers can do this.

One-time setup

The signing key

Our key signs the GitHub APKs and is the Google Play upload key; Google keeps the key that signs the Play app (ADR 0019). It was created with:

keytool -genkeypair -storetype PKCS12 -keystore pastello-release.jks \
  -alias pastello -keyalg RSA -keysize 4096 -validity 10950 \
  -dname "CN=Pastello, O=Pastello project"

• Keep at least two offline backups of the keystore and its password (for example an encrypted USB drive and a password manager). Losing them means the GitHub APKs can no longer be updated; on Google Play the upload key can be reset through Play Console support.
• Never commit it: *.jks, *.keystore and key.properties are ignored.
• To build a signed release locally, put a key.properties in app/android/ (storeFile, storePassword, keyAlias, keyPassword).

GitHub

1. Environment: Settings → Environments → New environment release. Under “Deployment branches and tags” choose “Selected branches and tags” and add the tag rule v*.*.*.

2. Secrets of the release environment:

   Secret	Value
   PASTELLO_KEYSTORE_BASE64	base64 -w0 pastello-release.jks
   PASTELLO_KEYSTORE_PASSWORD	the keystore password
   PASTELLO_KEY_ALIAS	pastello
   PASTELLO_KEY_PASSWORD	the key password (same as the keystore’s)

3. Pages: Settings → Pages → Deploy from a branch → main, /docs. The privacy policy is then at https://pegperego.github.io/pastello-app/privacy-policy.html.

Google Play

These are the answers given when Pastello was created; re-check them when Play’s forms change.

1. Create app: name “Pastello – Disegna e colora”, default language Italian, app, free; package name io.github.pegperego.pastello (it can never change). Accept the Developer Program Policies and the US export laws declarations.
2. App signing: keep the key generated by Google. The first AAB uploaded registers our key as the upload key.
3. App content:
   • Privacy policy: the GitHub Pages URL above.
   • App access: all functionality is available without special access (the parents’ page only asks for an addition, whose answer is shown on screen).
   • Ads: no ads.
   • Content rating (IARC): email pastello.app@proton.me, category “All other app types”, every answer “No” (users do not interact through the app: sharing goes through Android’s share sheet behind the parental gate). Expected rating: PEGI 3, ESRB Everyone.
   • Target audience: ages 5 and under, 6–8, 9–12, so the app joins the Families program; no ads or third-party SDKs.
   • Data safety: no data collected or shared (the app has no internet permission; saving, printing and sharing are started by the user).
   • Advertising ID, government app, financial features, health, news app: no.
4. Store listing: texts and images are in fastlane/metadata/android/ (it-IT as the default listing, en-US as a translation): title, short and full description, icon, feature graphic, phone and 10-inch tablet screenshots.
5. Store settings: category “Art & Design”; contact email pastello.app@proton.me; website https://github.com/pegperego/pastello-app.
6. Internal testing: an email list with the family’s accounts. Closed testing is not required: the developer account is not a new personal one.

Publishing with fastlane

fastlane uploads the builds and the store listing (ADR 0023).

1. Service account: in Google Cloud Console, in a project of the developer account, enable the Google Play Android Developer API, then create a service account (for example pastello-publisher) with no roles, and create a JSON key for it. Download it once and keep it with the keystore backups, never in the repository.
2. Play Console: Users and permissions → Invite new users → the service account’s email. Give access to Pastello only, with: release to production, exclude devices and use Play App Signing; release apps to testing tracks; edit store listing, pricing and distribution. Nothing else.
3. GitHub: Settings → Environments → New environment google-play. Under “Deployment branches and tags” choose “Selected branches and tags” and add the branch main and the tag rule v*.*.*. Add the secret PASTELLO_PLAY_SERVICE_ACCOUNT with the whole content of the JSON key.

4. Check: run the Google Play workflow with the task listing, or locally:

   bundle install
   PASTELLO_PLAY_KEY=/path/to/key.json bundle exec fastlane android check
   

Every release

1. Update version: in app/pubspec.yaml: X.Y.Z+N, where N grows by one every release (it is the Android version code).
2. Move the [Unreleased] notes of CHANGELOG.md under a new ## [X.Y.Z] - YYYY-MM-DD section and update the links at the bottom.
3. Add fastlane/metadata/android/<locale>/changelogs/N.txt (at most 500 characters) in both languages.

4. Merge to main through a pull request, then tag the merge commit:

   git tag -a vX.Y.Z -m "Pastello X.Y.Z"
   git push origin vX.Y.Z
   

5. The Release workflow checks that the tag matches the version, builds and signs the APK and the AAB, checks the permissions and the signature, and publishes a GitHub Release with the APK and its SHA-256. Then it uploads the AAB to Google Play internal testing, with the release notes and the store listing from fastlane/metadata/android/.
6. Install the internal testing build on a real device and go through the checks below.
7. Actions → Google Play → Run workflow, task production, version X.Y.Z: the version is promoted from internal testing to production, where Google reviews it before it reaches the families.

The store listing is taken from the repository at every upload: change texts and screenshots in fastlane/metadata/android/, not in Play Console. To publish a listing change without a new version, run the Google Play workflow with the task listing.

Checks on a real device before production

• Install from the internal testing track and open an existing drawing.
• The icon is right in the launcher and in Google Kids Space (a sideloaded build showed a generic icon there; it should come from Play).
• A build from Google Play cannot update a GitHub APK, and the other way round: switching needs an uninstall, which deletes the drawings.
• Save to gallery, print and share work.

This site is open source. Improve this page.