Release Process

This app is built as 2 different flavors:

OONI Probe: the general official probe used for collecting mobile data
News Media Scan: a probe specific for news sites, created in partnership with Deutsche Welle

Each flavor is available for Android and iOS devices, through different platforms:

Additionally, the OONI Probe Desktop app is distributed both as direct downloads (DMG/EXE, self-updating via Sparkle/WinSparkle) and through the desktop app stores:

OONI Probe Desktop on the Mac App Store
OONI Probe Desktop on the Microsoft Store

Continuous Deployment

Pull-requests merged into the main branch trigger a new OONI Probe Android and News Media Scan Android builds that are automatically published to Firebase.

Release Process

Here are the steps required to release a new app version across all platforms.

1. Prepare Release

1.1 Create release branch

Create a new release branch named releases/NEW_VERSION where NEW_VERSION in the new version to be released.

1.2 Update the version

versionCode is an integer number that must be incremented every time there’s a new release. It should be increased in increments of 10 to allow for different versionCodes for each split APK for F-droid.

versionName is the public version of a release. The app is versioned by combining 3 numbers: MAJOR.MINOR.PATCH:

PATCH is incremented if a release only includes bug fixes, dependency updates or copy/translation changes;
MINOR is incremented if a release includes new features or changes in user experience (PATCH resets to 0);
MAJOR is incremented only if a release includes significant new features or changes (MINOR AND PATCH reset to 0).

For Android and Desktop, update the versionCode and versionName at composeApp/build.gradle.kts.

For iOS, update the BUNDLE_VERSION to match versionCode and APP_VERSION to match versionName at iosApp/Configuration/Config.xcconfig.

1.2.1 Run Xcode Cloud workflow

Run the Xcode Cloud workflow if not triggered automatically to ensure all iOS related actions for release are able to run. It may fail due to differences in Xcode versions, macOS versions, or CI configuration. Use the build logs to diagnose and fix any issues, then re-run the build.

Once the build passes, update the build number under Xcode Cloud > CI/CD > Settings to match your release versioning.

1.3 Release notes

Update the release notes for all flavors and platforms at metadata/ooni/android/en-US/changelogs/default.txt.

Ensure the release note includes the current engine version as part of the release note.

1.4 Create the Pull Request

Push the branch to Github and create a Pull Request for it against main. Make sure CI validations complete successfully.

1.5 Android alphas

Distribute Closed Testing (alpha) builds of the OONI Probe Android and News Media Scan Android apps on Google Play, so the OONI team and partners can test them.

Go to Publish Android on Google Play, press Run Workflow, pick the new release branch, pick alpha as the track, select both apps and press Run Workflow. Confirm both actions run successfully.

2. Publishing

Once the alpha versions have been approved for release, we can start publishing.

2.1 Tag & Merge Release

2.1.1 Tag the latest commit on the release branch:

git tag -s v[x.y.z] -f -m "[x.x.x] release"
git push origin tag v[x.y.z]

2.1.2 Merge the release branch PR into main, always through a merge commit! We don’t want to lose our tagged commit.

2.2 Publish iOS Apps

Creating a new tag on GitHub will trigger an Xcode Cloud build for the tagged commit. Assuming the trial build from section 1.2 Update the version has passed, proceed with the following steps:

Steps to publish using Xcode Cloud and App Store Connect:

After creating and pushing the tag (see section 2.1 Tag & Merge Release), verify that the Xcode Cloud build completes successfully.
In App Store Connect > TestFlight, locate the new build and add it to Internal Testing so your team can verify it before public release.
Under App Store Connect > My Apps > [OONI Probe/NMS] > Distribution, create a new release entry for the build, add the changelog and other required metadata, and submit for App Store review. Monitor the review status, as App Store approval may be required for public releases.

2.3 Publish OONI Probe Android on F-Droid

By pushing a new tag on Github, F-Droid bots will check if our app versionCode was updated. Since it was, they will trigger a new build and release it automatically. It should take around 3 days for the new release to be available here but sometimes it can take more time.

2.4 Publish OONI Probe Android on Huawei AppGallery

Go to Publish OONI Probe on Huawei AppGallery, press Run Workflow, use workflow from the new tag and press Run Workflow. Confirm the action ran successfully.

2.5 Promote News Media Scan Android

Go to Promote Android on Google Play, press Run Workflow, pick the Organization dw, the Current Track alpha, the Promote Track production and press Run Workflow. Confirm the action ran successfully.

2.6 Promote OONI Probe Android

Since this is our app with the biggest amount of users, we take more steps to release it. First we promote from alpha to beta, and then from beta to production with a 0.2 (20%) rollout value.

Both steps are done at Promote Android on Google Play like on the previous step, but with the Organization as ooni.

2.7 Publish OONI Probe Desktop (direct downloads)

2.7.1 Generate apps

Go to Desktop package apps, press Run Workflow, use workflow from the new tag, tick MacOS and Windows, and press Run Workflow. Confirm the action ran successfully and download the generated apps (zipped artifacts).

2.7.2 Sign windows app

We need to sign the windows .exe file using our Extended Validation certificate. Follow the steps on our internal process to do so.
Generate the WinSparkle appcast for the signed .exe file.

2.8 Publish OONI Probe Desktop (app stores)

The app store builds are produced from the same workflow but with different distribution targets (-PdesktopDistribution=mac-appstore / -PdesktopDistribution=ms-store). These builds are sandboxed and have the Sparkle/WinSparkle self-updaters stripped out, since updates are handled by the stores.

2.8.1 Generate the store apps

Go to Desktop package apps, press Run Workflow, use workflow from the new tag, tick macOS App Store (PKG) and Windows Store (EXE), and press Run Workflow. Confirm the action ran successfully and download the desktopApps-macos-appstore-* (.pkg) and desktopApps-windows-appstore-* (.exe) artifacts.

2.8.2 Publish to the Mac App Store

Build and upload locally for now. CI not set up properly

Upload the signed .pkg to App Store Connect (via Transporter, or xcrun altool/xcrun notarytool per our internal process) using the Mac App distribution certificate/provisioning profile.
In App Store Connect > My Apps > OONI Probe (macOS) > Distribution, create a new release entry for the uploaded build, add the changelog and required metadata, and submit for App Store review.
Monitor the review status; App Store approval is required before the macOS build goes public.

2.8.3 Publish to the Microsoft Store

Sign in to Partner Center and open the OONI Probe Desktop app submission.
Upload the Microsoft Store .exe package to an s3 bucket and link the release, update the changelog and required metadata, and submit for certification.
Monitor the certification status; Microsoft Store approval is required before the Windows build goes public.

2.9 Create Release

2.9.1 Create a new Github release based on the new tag.

2.9.2 Write our manual release notes and add at the bottom the automatic changelog using the Generate release notes button.

2.9.3 Upload all the desktop files downloaded during step 2.7.1, and swapping the windows .exe files for their signed versions (step 2.7.2).

It’s important the file names are OONI-Probe-VERSION.dmg and OONI-Probe-VERSION.exe so the OONI website can link them automatically correctly.

The app store packages (.pkg/store .exe from step 2.8) are not uploaded to the Github release — they are delivered through the Mac App Store and Microsoft Store only.

2.9.4 Publish release

The new Github release post an internal Slack message warning of the new incoming release.

Monitoring

We use Sentry to monitor for crashes and handled errors. We have specific views for:

We also monitor the number of uploaded measurements to OONI Explorer through our internal Grafana dashboard.

Store Listings

Capture Android screenshots

There is a fastlane command to capture new screenshots of the app (organization can be ooni or dw):

bundle exec fastlane android capture_screens organization:ooni

Only the screenshots 1-5 are committed to git, since those are the ones we submit to Google Play.

Capture Mac App Store desktop screenshots

desktopCaptureScreensMacAppStore renders the same flows as desktopCaptureScreens but at a logical 1280×800 viewport with 2x density, producing 2560×1600 PNGs that App Store Connect accepts as the retina Mac App Store screenshot size (no downscale needed):

./gradlew :composeApp:desktopCaptureScreensMacAppStore \
  -Porganization=ooni \
  -Plocales=en-US

Output: fastlane/metadata/<organization>/desktop/mac-app-store/<locale>/*.png.

The smaller desktopCaptureScreens task (480×800 portrait, for parity with the Android fastlane dataset) continues to write to fastlane/metadata/<organization>/desktop/<locale>/ unchanged.

Update Google Play listings

To update the screenshots or the metadata (title, short and full description) of the OONI Probe and News Media Scan Android apps, go to Update Google Play information.

Update Apple App Store listings

To update the screenshots or the metadata (title, short and full description) of the OONI Probe and News Media Scan iOS apps, go to Update Apple App Store information.

Update F-Droid listing

On release, F-Droid should pick up the OONI Probe screenshots and metadata automtically from the repository.

Updating Huawei AppGallery listing

The Huawei AppGallery listing must be updated manually.