macOS with Homebrew:
brew install --cask marlonjd/tap/mobile-releaseThe initial v0.1.0 source formula can also be installed with:
brew install marlonjd/tap/mobile-releaseWindows with Scoop:
scoop bucket add marlonjd https://github.com/MarlonJD/scoop-bucket
scoop install marlonjd/mobile-releaseWindows with WinGet, after the package is accepted into the public WinGet community repository:
winget install MarlonJD.MobileReleaseLinux can install the .deb or .rpm package from GitHub Releases:
sudo apt install ./mobile-release*.deb
sudo dnf install ./mobile-release*.rpmDirect archives are published on GitHub Releases for every supported OS/architecture:
darwin/amd64, darwin/arm64
linux/amd64, linux/arm64
windows/amd64, windows/arm64
Any platform with Go installed:
go install github.com/MarlonJD/mobile-release-tools/cmd/mobile-release@v0.2.2Verify:
mobile-release --helpFull installation and maintainer publishing details are in docs/installation.md.
mobile-release-tools provides mobile-release, a local-first release CLI for
iOS and Android applications. It exists to make mobile shipping repeatable
without forcing the project to depend on paid CI, a hosted release service, or
manual release-note/version bookkeeping.
The CLI keeps the release mechanics that should be shared across platforms in one portable Go binary:
- Semantic Versioning bump calculation.
- Conventional Commits changelog generation.
- Artifact SHA-256 hashing.
- Release manifest generation.
- Android
.aabpackaging through Gradle. - iOS
.ipapackaging through Xcode archive/export.
It does not replace the official platform toolchains:
- Android signing is still handled by Gradle and the configured upload key.
- iOS signing and provisioning are still handled by Xcode.
- Google Play and App Store Connect upload/review/release remain explicit release-owner steps.
Mobile releases usually fail in boring, expensive ways: reused build numbers, missing changelog notes, unsigned or incorrectly signed artifacts, unclear artifact paths, and local steps that differ from CI steps. This project keeps those decisions in a small CLI so the release process is the same whether it is run on a developer machine or later moved into CI.
The intended model is:
- Prepare release metadata locally.
- Build the signed platform artifact locally.
- Hash and summarize the produced artifact.
- Upload manually to App Store Connect or Google Play.
- Optionally run the same commands in CI later.
Go is used because this is a cross-platform release orchestrator, not an app runtime dependency. The CLI can be shipped as one binary for macOS, Linux, and Windows, while platform-specific packaging stays delegated to Xcode and Gradle.
Homebrew binary install:
brew install --cask marlonjd/tap/mobile-releasePinned source install with Go:
go install github.com/MarlonJD/mobile-release-tools/cmd/mobile-release@v0.2.2Or clone and run directly:
git clone https://github.com/MarlonJD/mobile-release-tools.git
cd mobile-release-tools
go test ./...
go run ./cmd/mobile-release --helpInstall options and package-manager publishing details are documented in docs/installation.md.
This section is for maintainers publishing a new mobile-release CLI version.
It is separate from using the CLI to package an iOS or Android app.
One-time setup:
- Keep these package-manager repositories available:
MarlonJD/homebrew-tapMarlonJD/scoop-bucketMarlonJD/winget-pkgs, forked frommicrosoft/winget-pkgs
- In
MarlonJD/mobile-release-tools, add repository secrets atSettings -> Secrets and variables -> Actions:RELEASE_PUBLISH_TOKEN: GitHub personal access token that can write toMarlonJD/homebrew-tapandMarlonJD/scoop-bucket.WINGET_TOKEN: GitHub personal access token that can write toMarlonJD/winget-pkgs.
- For public repositories, a classic GitHub personal access token with the
public_reposcope is enough. A fine-grained token can also be used withContents: Read and writeandPull requests: Read and writeon the three package-manager repositories.
Publish a new CLI version:
Commit the release change first, then tag the exact commit that should be published:
go test ./...
git status --short
git push origin main
git tag vX.Y.Z
git push origin vX.Y.ZPushing the tag publishes direct GitHub Release assets automatically:
- macOS/Linux/Windows archives.
checksums.txt.- Linux
.debpackages. - Linux
.rpmpackages.
After the tag release succeeds, run the Release workflow manually on the same
tag with publish_package_managers=true to publish package-manager metadata:
gh workflow run release.yml --ref vX.Y.Z -f publish_package_managers=true- Homebrew Cask to
MarlonJD/homebrew-tap. - Scoop manifest to
MarlonJD/scoop-bucket. - WinGet manifest PR from
MarlonJD/winget-pkgstomicrosoft/winget-pkgs.
If package-manager repositories or secrets are not ready yet, the tag release is
still valid; users can install from GitHub Releases, .deb, .rpm, or the
pinned Go install.
mobile-release is normally run from the app monorepo root. The current default
paths match this layout:
apps/
android/
gradlew
app/build.gradle.kts
ios/
emsi_ios.xcodeproj
release/ExportOptions-app-store.plist
You can override all important paths with command flags, so the CLI can be used outside this exact layout.
Requirements:
- macOS with Xcode installed.
- An Apple Developer account available to Xcode.
- A valid distribution certificate/provisioning setup for the app bundle ID.
- An Xcode project and shared scheme.
- An export options plist committed in the app repository.
Create the export options file:
mkdir -p apps/ios/releaseapps/ios/release/ExportOptions-app-store.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>destination</key>
<string>export</string>
<key>manageAppVersionAndBuildNumber</key>
<false/>
<key>method</key>
<string>app-store-connect</string>
<key>signingStyle</key>
<string>automatic</string>
<key>stripSwiftSymbols</key>
<true/>
<key>teamID</key>
<string>YOUR_TEAM_ID</string>
<key>uploadSymbols</key>
<true/>
</dict>
</plist>Replace YOUR_TEAM_ID with the Apple Developer Team ID used by the app target.
Package a signed .ipa:
mobile-release package iosWhat this runs:
xcodebuild test ...
xcodebuild archive ...
xcodebuild -exportArchive ...Default output:
build/releases/ios/<version>+<build>/
emsi_ios.xcarchive
export/*.ipa
RELEASE_NOTES.md
release-manifest.json
The current version and build are read from the Xcode project file
(MARKETING_VERSION and CURRENT_PROJECT_VERSION). The next version is
calculated from Conventional Commits, and the next build increments the current
project build. Git tags are used only to find the changelog range. Use
--dry-run to print the commands and final upload summary without running
Xcode.
The default iOS command assumes:
- Project:
apps/ios/emsi_ios.xcodeproj - Scheme:
emsi_ios - Export options:
apps/ios/release/ExportOptions-app-store.plist - Xcode provisioning updates: enabled
Override those flags only when the app uses different paths or when signing must be fully pre-provisioned.
Requirements:
- JDK and Android SDK installed.
- A Gradle wrapper in the Android project.
- An Android app module, usually
:app. - Release signing configured through environment variables or Gradle properties.
- A Gradle build that accepts:
emsi.versionNameemsi.versionCodeemsi.distributionChannel
For environment-based signing, set:
export EMSI_ANDROID_RELEASE_STORE_FILE=/absolute/path/to/upload-key.jks
export EMSI_ANDROID_RELEASE_STORE_PASSWORD=...
export EMSI_ANDROID_RELEASE_KEY_ALIAS=...
export EMSI_ANDROID_RELEASE_KEY_PASSWORD=...Package a signed .aab:
mobile-release package android \
--project apps/android \
--channel productionWhat this runs:
./gradlew :app:testDebugUnitTest
./gradlew :app:bundleRelease \
-Pemsi.versionName=<computed-version> \
-Pemsi.versionCode=<computed-build> \
-Pemsi.distributionChannel=productionDefault Gradle output:
apps/android/app/build/outputs/bundle/release/app-release.aab
build/releases/android/<version>+<build>/RELEASE_NOTES.md
build/releases/android/<version>+<build>/release-manifest.json
The current version and build are read from apps/android/app/build.gradle.kts
by default. Use --build-file when the app keeps versionName and
versionCode in another Gradle file.
Signing modes:
--signing env: default; requires allEMSI_ANDROID_RELEASE_*variables.--signing external: use when Gradle properties or CI secrets provide signing outside environment variables.--signing unsigned: use only for local QA artifacts that will not be uploaded to Google Play.
Use --include-apk to also run :app:assembleRelease for QA builds. Use
--dry-run to print the commands without running Gradle.
-
Build the platform artifact:
mobile-release package android --channel production
mobile-release package ios
The package command automatically:
- Reads the current app version/build from the platform project file.
- Finds the latest SemVer git tag, using the
vprefix by default, only for the changelog range. - Infers the next SemVer bump from Conventional Commits.
- Computes the next platform build number from the current platform build.
- Passes the computed version/build into Gradle or Xcode.
- Writes
RELEASE_NOTES.md. - Writes
release-manifest.jsonwith artifact SHA-256 hashes and sizes. - Prints the upload destination and artifact path at the end.
-
Upload the artifact listed in the terminal summary:
- Android
.aabto Google Play Console. - iOS
.ipato App Store Connect through Xcode Organizer, Transporter, orxcrun altool/Transporter tooling.
- Android
mobile-release bump --current 1.4.2 --level patch|minor|major
mobile-release changelog --repo . --from v1.4.2 --to HEAD --version 1.4.3 --output RELEASE_NOTES.md
mobile-release hash --file path/to/artifact
mobile-release manifest --platform ios|android --version 1.4.3 --build 104 --artifact path --notes RELEASE_NOTES.md --output manifest.json
mobile-release package android --channel production [--build-file apps/android/app/build.gradle.kts]
mobile-release package iosRelease notes are generated from Conventional Commit subjects between the last released tag and the target ref.
User-facing sections are generated for:
feat: Featuresfix: Bug Fixesperf: Performancesecurity: Security!orBREAKING CHANGE: Breaking Changes
Internal-only commit types such as chore, ci, build, test, docs,
style, and refactor are skipped by default. Use --include-internal when an
internal release log is needed.
The CLI follows Semantic Versioning for the shared marketing version and keeps platform build counters separate:
- iOS:
CFBundleShortVersionStringis SemVer;CFBundleVersionis a monotonic build number. - Android:
versionNameis SemVer;versionCodeis a monotonic integer.
Example release id:
1.5.0+105
Automatic package versioning uses these rules:
- Current iOS version/build are read from
apps/ios/emsi_ios.xcodeproj/project.pbxprojby default. - Current Android version/build are read from
apps/android/app/build.gradle.ktsby default. - Git tags do not define the active app version. They define the previous release point for changelog generation.
BREAKING CHANGEor!: major bump.feat: minor bump.fix,perf, orsecurity: patch bump.- Internal-only commits default to patch when packaging is explicitly requested.
- The next build is the current platform build plus one.
Use --version or --build only for an explicit release-owner override.
Android signing error:
android signing env is incomplete
Set the EMSI_ANDROID_RELEASE_* variables, use --signing external if Gradle
properties provide signing, or use --signing unsigned only for QA artifacts.
iOS export fails because signing assets are missing:
- Confirm the app target has the correct Team ID and bundle ID.
- Sign into Xcode with the Apple Developer account.
mobile-release package iosallows Xcode provisioning updates by default. Pass--allow-provisioning-updates=falseonly when signing assets must already exist locally.
The app version changed after export:
- Keep
manageAppVersionAndBuildNumberset tofalsein the export options plist. - Use the platform project file as the source of truth for the current version,
and use the terminal summary from
mobile-release package iosfor the computed release candidate. Pass--versionor--buildonly when intentionally overriding the automatic calculation.
Copyright (C) 2026 Burak Karahan.
This project is licensed under the GNU General Public License v3.0 or later. See LICENSE and NOTICE.