The README sets out the listing each app keeps in its own repository, in the layout Google Play's tools read and F-Droid accepts as it is: name, short and full description, icon, banner and phone screenshots, per language. listing/banner.py draws an app's banner, the feature graphic Google Play asks for and the picture at the top of an app's page in F-Droid: the app's mark in a round seal, its name and its address between two hairlines, on paper in its own colours and typeface, 1024 by 500 pixels without transparency. banners.json holds the portal, "me-web?", SimpleSchool and Passolo; the fonts are open-licence copies, listed in fonts/NOTICE.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W4YtEKqxKjKyHkFzuRVMNA
245 lines
13 KiB
Markdown
245 lines
13 KiB
Markdown
# app-stores
|
||
|
||
Three Gitea Actions for any project's release workflow: `play` publishes to Google Play, `apple` to the App Store,
|
||
and `changelog` writes what changed since the previous release from the commit messages, in every format a release
|
||
needs. Each is one Python file; the store ones talk to the store's own web API (Google's Play Developer API, Apple's
|
||
App Store Connect API). Nothing else is needed on the runner beyond Python 3.9 or newer and `openssl`, which every
|
||
Linux and Mac runner has. No fastlane, no Ruby, no service in between.
|
||
|
||
```yaml
|
||
- uses: https://git.thepra.dev/Arasaka/app-stores/play@v1
|
||
- uses: https://git.thepra.dev/Arasaka/app-stores/apple@v1
|
||
- uses: https://git.thepra.dev/Arasaka/app-stores/changelog@v1
|
||
```
|
||
|
||
> Status: checked against fakes of both stores built from their published API definitions (Google's discovery
|
||
> document of 22 October 2026, Apple's OpenAPI 4.5.1), with every request body, query and signature verified, and
|
||
> called by URL from jobs on both of this Gitea's runners, where both stores refused only the made-up keys. Not yet
|
||
> run against a real store account; the first project to use one is the first real run.
|
||
|
||
## Google Play: `play`
|
||
|
||
Two things it does, one per run:
|
||
|
||
- **Upload**: given `aab`, it uploads the bundle and puts it on `track`.
|
||
- **Move**: given `from-track`, it takes the newest release already on that track and puts it on `track`, with
|
||
its notes unless `notes` is given. This promotes internal testing to production, raises a staged rollout
|
||
(`from-track: production`, `track: production`, a bigger `fraction`), completes it (`status: completed`) or halts
|
||
it (`status: halted`).
|
||
|
||
| Input | | |
|
||
|---|---|---|
|
||
| `service-account` | required | the JSON key of the service account, from a secret |
|
||
| `package` | required | the application id, `software.arasaka.meweb` |
|
||
| `aab` | upload | the signed `.aab` |
|
||
| `from-track` | move | the track to take the release from |
|
||
| `track` | `internal` | `internal`, `alpha` (closed testing), `beta` (open testing), `production` or a custom closed track |
|
||
| `status` | `completed` | `completed`, `draft`, `inProgress` (staged, needs `fraction`) or `halted` |
|
||
| `fraction` | | the share of users of a staged rollout, between 0 and 1 |
|
||
| `notes` | | a folder of `<language>.txt` files, `en-US.txt`, `it-IT.txt`, 500 characters each |
|
||
| `name` | | the release name in Play Console; Google uses the version name when empty |
|
||
|
||
Every tag on the internal testing track:
|
||
|
||
```yaml
|
||
- name: Google Play, internal testing
|
||
if: ${{ github.ref_type == 'tag' }}
|
||
uses: https://git.thepra.dev/Arasaka/app-stores/play@v1
|
||
with:
|
||
service-account: ${{ secrets.PLAY_SERVICE_ACCOUNT }}
|
||
package: software.arasaka.meweb
|
||
aab: dist/android/software.arasaka.meweb-Signed.aab
|
||
notes: store/notes
|
||
```
|
||
|
||
Production by hand, from the Actions tab:
|
||
|
||
```yaml
|
||
name: Google Play production
|
||
|
||
on:
|
||
workflow_dispatch:
|
||
inputs:
|
||
fraction:
|
||
description: "Share of users, 0.1 for 10%; empty for everyone"
|
||
default: "0.1"
|
||
|
||
jobs:
|
||
promote:
|
||
runs-on: nuvola
|
||
steps:
|
||
- uses: https://git.thepra.dev/Arasaka/app-stores/play@v1
|
||
with:
|
||
service-account: ${{ secrets.PLAY_SERVICE_ACCOUNT }}
|
||
package: software.arasaka.meweb
|
||
from-track: internal
|
||
track: production
|
||
status: ${{ inputs.fraction && 'inProgress' || 'completed' }}
|
||
fraction: ${{ inputs.fraction }}
|
||
```
|
||
|
||
## App Store: `apple`
|
||
|
||
- **Upload**: given `ipa`, it reads the version and build number from the app's `Info.plist`, uploads it, waits
|
||
until Apple has processed it (up to an hour and a half), writes what to test from `notes`, and gives it to the
|
||
TestFlight `groups`. A group outside the team (external testers) also sends the build to TestFlight review.
|
||
- **Submit**: with `submit: true`, it sends the build for App Store review: the uploaded one, or the newest
|
||
processed build of `version` (or exactly `build`) when no `ipa` is given. It reuses the version waiting to be
|
||
submitted, or creates it, links the build, writes what is new from `notes`, and submits. With `release:
|
||
after-approval` the version goes on sale when Apple approves it; with `manual` it waits for you in App Store
|
||
Connect. `phased: true` spreads the update over seven days.
|
||
|
||
| Input | | |
|
||
|---|---|---|
|
||
| `issuer-id`, `key-id`, `private-key` | required | the team API key: two ids and the text of the `.p8` file, from secrets |
|
||
| `bundle-id` | required | the app's bundle identifier |
|
||
| `ipa` | upload | the signed `.ipa` |
|
||
| `notes` | | a folder of `<locale>.txt` files, `en-US.txt`, `it.txt`, 4,000 characters each |
|
||
| `groups` | | TestFlight groups by name, separated by commas or lines |
|
||
| `submit` | `false` | `true` sends the build for App Store review |
|
||
| `version`, `build` | submit | which build to submit when no `ipa` is given |
|
||
| `release` | `after-approval` | or `manual` |
|
||
| `phased` | `false` | `true` for a seven-day phased release |
|
||
|
||
The build itself needs a Mac with Xcode; the upload does not. A Mac job can build, sign and run this step itself,
|
||
or hand the `.ipa` to a Linux job that runs it:
|
||
|
||
```yaml
|
||
- name: TestFlight
|
||
uses: https://git.thepra.dev/Arasaka/app-stores/apple@v1
|
||
with:
|
||
issuer-id: ${{ secrets.ASC_ISSUER_ID }}
|
||
key-id: ${{ secrets.ASC_KEY_ID }}
|
||
private-key: ${{ secrets.ASC_PRIVATE_KEY }}
|
||
bundle-id: software.arasaka.meweb
|
||
ipa: dist/ios/MeWeb.ipa
|
||
notes: store/notes
|
||
groups: Team
|
||
```
|
||
|
||
## Once per app, by hand
|
||
|
||
Neither store lets an API create an app, so the first steps happen in their consoles.
|
||
|
||
**Google Play**
|
||
|
||
1. A Play Console developer account ($25 once). A personal account opened after 13 November 2023 must run a closed
|
||
test with at least 12 testers for 14 days before it can publish to production; an organisation account needs a
|
||
D-U-N-S number.
|
||
2. Create the app and fill in what Play Console asks before a first release: the store listing, the content rating
|
||
questionnaire, the target audience, data safety and a privacy policy address.
|
||
3. Upload the first `.aab` by hand, on internal testing. Play asks then which key signs the app for users (Play
|
||
App Signing). To keep a copy installed from a website and the Play copy updating each other, give Play the key
|
||
the website APK is already signed with, rather than letting Google generate a new one. The choice is permanent.
|
||
4. In Google Cloud, create a project, enable the **Google Play Android Developer API**, create a service account,
|
||
and make a JSON key for it. Store the whole file as a secret (`PLAY_SERVICE_ACCOUNT`).
|
||
5. In Play Console, Users and permissions, invite the service account's email address with release rights for
|
||
this app (testing tracks, and production if a workflow promotes to it).
|
||
6. Until the app's first release is published by hand in Play Console, Google accepts only `status: draft`.
|
||
|
||
**App Store**
|
||
|
||
1. The Apple Developer Program ($99 a year).
|
||
2. Register the bundle identifier (Certificates, Identifiers and Profiles) and create the app in App Store Connect.
|
||
3. Fill in the App Privacy answers, the age rating, the screenshots, the description and the support address for
|
||
the first version.
|
||
4. Users and Access, Integrations, App Store Connect API: generate a **team key** with the App Manager role. Store
|
||
the issuer id, the key id and the text of the `.p8` file (downloadable once) as three secrets.
|
||
5. Put `ITSAppUsesNonExemptEncryption` in the app's `Info.plist`. Without it every build waits for an export
|
||
compliance answer in App Store Connect, so the action refuses the upload.
|
||
6. Create the TestFlight groups. An external group needs the Beta App Review information (contact and notes)
|
||
filled in once.
|
||
|
||
## Release notes: `changelog`
|
||
|
||
**The commit messages are the changelog** (owner, 1 November 2026: every commit between two releases, the whole
|
||
message, in every place a release is shown). The action takes the commits since the previous tag of the same kind
|
||
(`prefix`: `v`, `app-v`, `server-v`; the previous one is the highest lower version among those tags), leaves out merges
|
||
and the `Co-Authored-By`, `Signed-off-by` and Claude attribution lines, and writes, into `output`:
|
||
|
||
| File | For |
|
||
|---|---|
|
||
| `notes.md` | "What's new in <name> <version>": each commit's subject as a heading, its body below; the Releases tab, a page |
|
||
| `notes.txt` | the same as plain text: Velopack's `--releaseNotes`, an update dialog, F-Droid |
|
||
| `CHANGELOG.md` | the last `history` releases, newest first |
|
||
| `changelog.yml` | the same releases for nfpm's `changelog:` (chglog), so the deb carries `changelog.Debian.gz` and the rpm its `%changelog`; bodies become one line per paragraph |
|
||
| `notes.json` | everything above as data |
|
||
| `store/en-US.txt` | the subjects, cut to 500 characters, for the `notes` folder of `play` and `apple` |
|
||
|
||
With `release: 'true'` it also writes the notes onto this tag's release on the Releases tab: it creates the release
|
||
when there is none, and otherwise replaces only what sits between `<!-- changelog -->` and `<!-- /changelog -->`
|
||
(adding that block at the end the first time), so a release text written by the project itself stays. Give the job
|
||
`permissions: contents: write`.
|
||
|
||
```yaml
|
||
- uses: actions/checkout@v4
|
||
- name: Release notes
|
||
id: notes
|
||
uses: https://git.thepra.dev/Arasaka/app-stores/changelog@v1
|
||
with:
|
||
prefix: app-v
|
||
name: SimpleSchool
|
||
packager: Scuola di lingua Cinese di Varese <info@scuolacinese.org>
|
||
output: release-notes
|
||
release: 'true'
|
||
- run: echo "the notes are in ${{ steps.notes.outputs.dir }}, the previous release was ${{ steps.notes.outputs.previous }}"
|
||
```
|
||
|
||
| Input | | |
|
||
|---|---|---|
|
||
| `path` | `.` | the git checkout to read, when it is not the workspace itself |
|
||
| `prefix` | `v` | the tags of this kind of release |
|
||
| `tag` | the tag that started the run | the release being made; empty on a branch, which writes everything since the newest tag as `unreleased` |
|
||
| `name` | the repository's name | the product's name in headings |
|
||
| `strip` | | a regular expression removed from the start of each subject (me-web? removes its `“me-web?” 0.15.4: `) |
|
||
| `packager` | `Arasaka di Hvozdikov Yevheniy <https://arasaka.software/contact>` | `Name <address>` for the deb and rpm changelogs: the package's own maintainer |
|
||
| `history` | `20` | how many releases `CHANGELOG.md` and the package changelog carry |
|
||
| `output` | `release-notes` | the folder |
|
||
| `release` | `false` | `true` writes the notes onto the Releases tab |
|
||
| `token` | the job token | only with `release` |
|
||
|
||
A shallow checkout is fetched in full, with its tags, before anything is read. A first release lists its newest 100
|
||
commits. The same file reads the history from Gitea's API instead of a checkout (`--gitea URL --repository
|
||
owner/name`, token in `READ_TOKEN`); that is how `thepra/packages.arasaka.software` writes the notes for every app it
|
||
publishes, so the two can never tell a release differently.
|
||
|
||
## Store notes
|
||
|
||
One file per language, the file name being the code: Google uses language and region (`en-US`, `it-IT`), Apple
|
||
its own list (`en-US`, `it`, `de-DE`). Empty files are skipped. Apple takes no release notes for an app's first
|
||
version; the action leaves them out and says so.
|
||
|
||
## Store listing
|
||
|
||
Each app keeps its listing in its own repository, in the layout Google Play's tools read, so the same files serve
|
||
Google Play and F-Droid (`thepra/packages.arasaka.software` copies them into its F-Droid repository, mapping `it-IT`
|
||
to F-Droid's `it`):
|
||
|
||
```
|
||
fastlane/metadata/android/
|
||
en-US/
|
||
title.txt the name, up to 30 characters
|
||
short_description.txt up to 80 characters
|
||
full_description.txt up to 4,000 characters, plain text, "• " for a list
|
||
images/icon.png 512×512
|
||
images/featureGraphic.png 1024×500, no alpha
|
||
images/phoneScreenshots/ 1.png …, 1080×1920, no alpha, in the order shown
|
||
it-IT/ the same; a missing image falls back to en-US
|
||
```
|
||
|
||
`listing/banner.py <app> <target>` draws the banner (Google's feature graphic, the header of F-Droid's app page) for
|
||
an app named in `listing/banners.json`: its mark in a round seal, its name and its address between two hairlines,
|
||
in its own colours and typeface, at 1024×500 without alpha. Everything that matters sits in the middle, because
|
||
F-Droid trims a little off the top and bottom and puts its buttons over the top corners. It needs Python with Pillow and Chromium.
|
||
The marks are in `listing/marks/` (a mark may use `var(--accent)`, `var(--ink)` and `var(--well)`), the fonts in
|
||
`listing/fonts/`, each under the SIL Open Font License (`fonts/NOTICE.md`).
|
||
|
||
```bash
|
||
python3 listing/banner.py meweb ../MeWeb/fastlane/metadata/android/en-US/images/featureGraphic.png
|
||
```
|
||
|
||
## Versions
|
||
|
||
`v1` moves forward with every change that keeps the inputs working; a change that breaks them becomes `v2`. Pin a
|
||
commit instead of `v1` to never move.
|