Releasing Coves #
This is for maintainers publishing the official Coves builds. You do not need any of it to build or run Coves from source -- see the README for that. Every step below requires access to the project's own store accounts and signing identity. A fork that wants to publish its own builds needs its own Apple and Google Play accounts, its own signing keys, and its own bundle identifier; the automation here is reusable, the credentials are not.
Release automation lives in android/fastlane and ios/fastlane, driven by
fastlane and CocoaPods, both pinned in Gemfile.lock.
Complete toolchain setup and activate mise before running
the commands below, so fastlane and pod use the project binstubs. Both
platforms share tool/fastlane_flutter.rb.
One-time credential setup #
Neither credential is in git, and neither can be created from the CLI -- both require a session in the respective web console.
Google Play #
The service account is created in Google Cloud Console; the Play Console only grants it access. Play Console's old Setup > API access page is being retired, and the named roles it used (Release manager and friends) no longer exist -- permissions are individual checkboxes now.
- Select or create a project, then enable the Google Play Android Developer API under APIs & Services.
- IAM & Admin > Service Accounts > Create service account (e.g.
fastlane-supply). Click Done -- skip the optional role grants. - On that account: Actions (⋮) > Manage keys > Add key > Create new key > JSON.
- Save the download as
android/fastlane/play-store-key.json(already gitignored), or pointPLAY_STORE_JSON_KEYat it elsewhere.
Then in Play Console, at the account level (not inside an app):
- Users and permissions > Invite new users, paste the service account
email (
...@<project>.iam.gserviceaccount.com). - Grant only what the upload lanes need: Release to production, exclude devices, and use Play App Signing + Release apps to testing tracks + View app information. Admin (all permissions) also works and is what most guides suggest, but it hands a CI-shaped credential far more authority than uploading a build requires.
Verify with cd android && fastlane run validate_play_store_json_key.
Two things that look like broken credentials but are not: newly granted permissions take a few minutes to propagate, so retry a first-run 401 before re-cutting the key; and the API refuses uploads for an app that has never been published manually (not an issue here -- Coves has shipped since 1.0.4+4).
App Store Connect #
-
App Store Connect > Users and Access > Integrations > App Store Connect API > generate a key with the App Manager role.
-
Download the
AuthKey_<KEY_ID>.p8-- Apple only serves it once. -
Export the three values fastlane needs, or put the same three lines (without
export) inios/fastlane/.env, which is gitignored and which fastlane loads automatically:export ASC_KEY_ID=XXXXXXXXXX export ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx export ASC_KEY_PATH=/secure/path/AuthKey_XXXXXXXXXX.p8
Keep the .p8 outside the repo. ios/fastlane/*.p8 is gitignored as a
backstop, not as an invitation.
Android signing #
The upload keystore is the third credential. android/key.properties
(gitignored) names it via storeFile, relative to android/app/, plus
storePassword, keyPassword and keyAlias; app/build.gradle.kts reads
those four keys. The keystore itself (*.jks, also gitignored) is maintainer
provided. tool/release verifies every AAB is signed by CN=Coves before
uploading.
Cutting a release #
One command ships both stores:
tool/release 1.4.0 # the version name is the only argument
tool/release 1.4.0 --dry-run # everything up to and including the builds
Before running it, write the "What's New" text to release_notes/<name>.txt.
Plain text, at most 500 characters (Play's limit), and do not name other
platforms -- Apple's precheck flags "Android" in metadata.
There is no confirmation prompt. The store numbers are printed before the
builds start, and nothing is uploaded until step 5, so Ctrl-C is safe until
then; any exit before the first upload restores the tree. A dry run may be
run from any branch (the main/origin checks are skipped) but still needs
both stores' credentials.
The script, in order:
- Preflight. Clean tree on
main, exactly in sync withorigin/main(neither behind nor ahead), installed locked Ruby dependencies, cleanflutter analyze, unchanged Dart formatting, and a completeflutter testrun with no failures or skips. The test gate cannot be bypassed. - Ask the stores.
fastlane store_state(Android: the production, beta, alpha and internal tracks) andfastlane latest_builds(iOS: every build ever uploaded) each writedist/store/<store>.json. Any App Store Connect error other than "no live version yet" stops the release here. The build number is one above the highest number seen anywhere, including the committed pubspec.pubspec.yamlis never the source of truth for the build number -- a build uploaded from a working copy leaves no git trace, and production once served1.0.5+7while the pubspec said1.0.5+6. Play version codes are global to the app; iOS scopes build numbers to the version string. Going above everything is always safe on both, so that is what happens. The name must be above the App Store's live version and not below the committed pubspec, and if App Store Connect already has a different version in preparation or review the script refuses to start. - Write.
version: <name>+<build>intopubspec.yaml; the notes intoandroid/fastlane/metadata/android/en-US/changelogs/<build>.txtandios/fastlane/metadata/en-US/release_notes.txt. - Build and verify.
fastlane buildon Android, then iOS. Each lane starts withflutter clean, which wipesbuild/for both platforms, so each copies its artifact todist/<version>/(gitignored) first. The AAB must be signed byCN=Covesand the IPA must carry a distribution profile (get-task-allowfalse) or the script stops here. - Ship.
fastlane shipon each platform, reading fromdist/<version>/:- Play: production track,
release_status: completed, 100% rollout, with the changelog. Google's review runs first; the release goes live when it passes. - App Store: uploads the build, pushes the whole text listing from
ios/fastlane/metadata, replaces the version's en-US screenshots withios/fastlane/screenshots/en-US(they lock once the version is submitted), creates the version, submits for review, releases automatically on approval, and then checks that the version is actually in a submitted state. Export compliance is answered byITSAppUsesNonExemptEncryptioninInfo.plist. Precheck runs at warning level: its URL rule sendsHEADand coves.social answers 405, so it reports the listing links as broken when they are not.
- Play: production track,
- Record. Commits
chore(release): <version>with the pubspec and notes and pushes toorigin.
If it fails after one store has shipped, the script prints exactly what is
half-done and how to finish: cd ios && fastlane ship if needed, then commit
pubspec.yaml and the two notes files and push. Do not re-run
tool/release; it would pick the next build number and leave the shipped one
uncommitted. If only the final push failed, the commit is local: push it.
The pre-automation lanes still exist for staging: android internal,
android production (draft), ios beta (TestFlight), ios release (upload
only). fastlane build on either platform produces the artifact without
uploading.
Store listings live in the repo #
android/fastlane/metadata and ios/fastlane/metadata hold the listing
text, and Android's also holds the icon, feature graphic and phone
screenshots. iOS screenshots (iPhone 6.9" iphone69_*, iPad 13" ipad13_*)
live in ios/fastlane/screenshots/en-US. Both were seeded from the
consoles. Android's ship pushes only the changelog; iOS's ship pushes the
full text listing and the screenshots, so a console-side edit to the iOS
listing is overwritten on the next release. Edit the files, not the console.
App Store screenshots belong to a version and lock once it is submitted, so
push_screenshots only works on a version still in preparation (or pulled
back from review). Play images are not tied to a release and can go up any
time, but supply needs exactly one release on the production track.
cd android && fastlane push_images # Play icon, banner, screenshots
cd android && fastlane supply # text + images
cd ios && fastlane push_screenshots version:<name> # editable version only
cd ios && fastlane push_metadata # text, no build
cd ios && fastlane pull_metadata # re-seed from ASC
cd ios && fastlane precheck # Apple's metadata rules
ios/fastlane/metadata/review_information/ comes down with pull_metadata
and holds the App Review contact and demo login. It is gitignored; keep it that
way.
Platform notes #
- Android builds the
prodflavor. Signing comes fromandroid/key.properties+ the keystore it references, both untracked. - iOS builds with no
--flavor. The Xcode project only defines Debug/Profile/Release with a singleRunnerscheme -- theProd-*/Dev-*xcconfigs exist but are not wired into it. A plain release build resolves to bundle idsocial.coves, andEnvironmentConfigdefaults to production. If iOS flavors are ever wired up properly, revisitios/fastlane/Fastfile. ios/fastlane/ExportOptions.plistis a near-copy ofios/ExportOptions.plistwithdestinationset toexportrather thanupload, so xcodebuild leaves an IPA on disk for fastlane to upload instead of shipping it directly.tool/fastlane_flutter.rbstripsGEM_*/RUBY*/BUNDLE*from the environment before invokingflutter. The projectbin/podmust derive its ownBUNDLE_GEMFILEand reload the locked bundle without inheriting fastlane's Ruby bootstrap settings. The helper keeps project binstubs first on PATH so Flutter uses the pinned CocoaPods executable.