Skip to main content
Version: 2.8

Test Builds & Obtainium

Obtainium installs and auto-updates Android apps straight from their GitHub releases — no Play Store account, no testing-track invite. This page sets it up for Meshtastic and shows how to follow the open beta, closed beta, or snapshot channels.

Builds from GitHub are signed with the project's release key (CN=Kevin Hester, O=Geeksville Industries), not Google Play's — if you already have Meshtastic installed from the Play Store, Android refuses to update over it. Switching between the fdroid and google flavors is fine: both flavors in a given release carry the same release key, so Obtainium can move you from one to the other in place (verified by installing the google APK over an installed fdroid build). Only the origin of a build (Play vs GitHub) determines whether the signatures clash.

⚠️ Warning: Uninstalling the Play Store version of Meshtastic clears the app's data — message history and settings on this phone are lost. Uninstall it before installing via Obtainium, then stay on Obtainium for updates.

Which channels can Obtainium reach?​

Meshtastic for Android promotes builds up a ladder: internal → closed → open → production. Each maps to a Google Play track. An internal build's GitHub release is a draft, which Obtainium can't see; it is published when the build is promoted to closed or higher.

ChannelPlay trackOn GitHubObtainium can install it?
stableProductionpublished, marked Latest✅ Yes
open betaBeta (Open)published prerelease, tag vX.Y.Z-open.N✅ Yes
closed betaAlpha (Closed)published prerelease, tag vX.Y.Z-closed.N✅ Yes
snapshot— (not on Play)rolling prerelease, tag snapshot✅ Yes

Each promotion moves the build's GitHub release to a new tag for its channel (vX.Y.Z-closed.N, then vX.Y.Z-open.N, then vX.Y.Z), and retitles it to match. A build that is not promoted further keeps its release, so during a version cycle a channel can hold several releases, and the channel configs in One-Tap Setup pick the newest release whose title matches the channel. Once the production release ships and its docs are published, post-release-cleanup.yml deletes every internal, closed, and open release and tag at or below that version.

Which release each channel resolves to is deliberately not listed on this page: it is archived per release tag and bundled into the app, so a live version number here would be frozen at build time and wrong within weeks. The project README carries the current state, refreshed automatically.

A channel can legitimately be empty: -open and -closed are empty between a production release and the next promotion, and -closed is often empty early in a cycle before any build has been cut to it. The number of published fdroid ABI splits has changed across releases, which is why the filter matches every split.

Snapshot is different: it's an automated debug build of the latest commit on main, rebuilt and re-published under the single moving snapshot tag on every push. It never goes to Play. Because debug builds use a .debug application-ID suffix (com.geeksville.mesh.fdroid.debug / com.geeksville.mesh.google.debug) and the debug signing key, a snapshot installs as its own separate app — it sits alongside a Play/stable/beta install, so the uninstall-first warning earlier on this page does not apply to it.

One-tap setup​

Tap a link in the following table on the phone that has Obtainium installed. Every setting from the rest of this page is already baked into it — pick the channel you want and the flavor you want (which flavor?).

Channelgoogle flavorfdroid flavor
StableAddAdd
Open betaAddAdd
Closed betaAddAdd
Bleeding edge (newest promoted test build)AddAdd
Snapshot (latest commit on main)AddAdd

Prefer a file? Import one of these via Import/Export → Obtainium import. Pick the one matching the flavor you want for the release build; each also sets up both snapshot flavors, which can coexist:

How many entries can you have at once?​

Obtainium keys apps by application ID, so the rule follows from ours:

Application IDCan coexist?
Release builds — stable, open, closed, bleeding edge, either flavorcom.geeksville.meshNo — pick exactly one
Snapshot, googlecom.geeksville.mesh.google.debugYes
Snapshot, fdroidcom.geeksville.mesh.fdroid.debugYes

At most one release entry plus the two snapshot entries. Tapping a second release link switches that single entry to the new channel or flavor instead of adding one, and importing both files in turn leaves you with whichever flavor's release entry came last. The snapshots are unaffected either way.

To set things up by hand instead, follow the rest of this page.

Manual setup​

  1. Install Obtainium (GitHub releases or F-Droid / IzzyOnDroid).
  2. Tap Add App.
  3. App Source URL: https://github.com/meshtastic/Meshtastic-Android
  4. Set the options for the channel you want — see Stable, Open beta, Closed beta, Bleeding edge, or Snapshot.
  5. Tap Add, then Install.

Stable​

  • Include prereleases: off
  • (optional, stricter) Verify the 'latest' tag: on
  • Filter APKs by regular expression: see Picking the APK

Open beta​

  • Include prereleases: on
  • Filter release titles by regular expression: -open
  • Filter APKs by regular expression: see Picking the APK

Closed beta​

  • Include prereleases: on
  • Filter release titles by regular expression: -closed
  • Filter APKs by regular expression: see Picking the APK

Bleeding edge (newest promoted test build, any channel)​

  • Include prereleases: on
  • Filter release titles by regular expression: -(closed|open)
  • Filter APKs by regular expression: see Picking the APK

Obtainium installs the newest promoted prerelease, whichever of open or closed it is. The title filter is required to skip the always-newer snapshot prerelease; without it Obtainium would follow snapshot instead.

Snapshot (latest commit on main)​

  • Include prereleases: on
  • Filter release titles by regular expression: ^Snapshot
  • Use the latest asset date as the release date: on
  • Version detection: off, with Release date as version on
  • Filter APKs by regular expression: debug-signed names, see the following table

Follows main directly — updates on every push. These are debug builds (.debug package, debug key), so they install as a separate app and won't disturb a stable/beta install. The snapshot tag never changes, so there is no version string to compare — date-based pseudo-versioning is what makes updates detectable.

The APKs are named …-debug-<versionCode>.apk (not -release.apk), so use debug-suffixed filters:

You wantRegex
google flavor, most phones (arm64)google-arm64-v8a-debug-\d+\.apk
fdroid flavor, most phones (arm64)fdroid-arm64-v8a-debug-\d+\.apk
fdroid flavor, one-size-fits-allfdroid-universal-debug-\d+\.apk

Snapshot releases attach the debug APKs and, for each platform whose build succeeded, the unsigned desktop installers from the same commit, each stamped with the versionCode. There is no .aab.

Local debug builds and CI snapshots are update-compatible: the repo checks in a shared debug keystore (config/debug.keystore) that both sign with, so Obtainium can update over your own debug install. INSTALL_FAILED_UPDATE_INCOMPATIBLE means the installed build predates the shared keystore (or was signed with another machine's default key) — uninstall that one build and reinstall.

Two more things about release selection apply to every channel described earlier, not just snapshot:

⚠️ Important: Leave Fallback to older releases on. It is not a channel-strictness setting, and turning it off breaks the beta and snapshot configs. Obtainium's release loop breaks out after the first candidate when fallback is off, so a title filter never gets to skip past non-matching releases. A config pinned to -open or ^Snapshot then fails with "Could not find a suitable release" when a newer production release sits at the head of the list. The title filter is what pins the channel; fallback is what lets Obtainium walk down to the newest release that matches it.

If your channel filter still finds nothing, that channel has no published release, which is common early in a version cycle and between a production release and the next promotion. Check the project README for what is live, or use the Bleeding edge form to follow whichever of open/closed is newest.

Picking the APK​

Each release attaches the google flavor APK, several fdroid flavor APKs, plus an .aab (not installable) and the desktop installers. Obtainium ignores non-APK assets on its own, but the two flavors share the com.geeksville.mesh package name, so exactly one must be pinned with Filter APKs by regular expression:

You wantRegex
Recommended for testing — google flavorgoogle-release\.apk
fdroid flavor, most phones (arm64)fdroid-arm64-v8a-release\.apk
fdroid flavor, one-size-fits-allfdroid-universal-release\.apk
fdroid flavor, let Obtainium pick the ABIfdroid-.*-release\.apk with Auto-select by architecture on

Use the google flavor while testing. It ships Firebase Crashlytics and Datadog RUM, so the crashes and errors you hit get reported back to the team — which is the whole point of a test phase. It also has Google Maps. Pick an fdroid flavor only if you'd rather not send that telemetry. You can change your mind later: both flavors share the release key, so Obtainium updates across the flavor boundary without an uninstall. Expect the google flavor to show its analytics-consent screen the first time it starts.

Version detection turns itself off — that's expected​

Release tags read vX.Y.Z, while our installed versionName reads X.Y.Z (versionCode) <flavor>. Obtainium tries to reconcile the two against a list of standard version formats, all of which are fully anchored — none of them tolerates the spaces and parentheses in our versionName. So on the first update check Obtainium logs Could not reconcile version formats for: com.geeksville.mesh, sets Version detection to off for the app, and records the release tag as the installed version.

This is harmless and you should not try to fix it. With detection off, Obtainium compares the release tag it last installed against the newest tag, so updates are still detected and installed normally. What you lose is only the ability to notice a version installed outside Obtainium.

In particular, do not set "Trim the version string" to \d+\.\d+\.\d+ hoping to fix it. That setting only rewrites the version parsed from the release; the unparseable side is the installed versionName, which it never touches — so reconciliation fails exactly as before. It also adds a failure mode: if the regex ever matches nothing (a tag without a three-part version), the update check fails outright with a "no version found" error instead of degrading quietly.

Snapshot is a separate case: its tag is the literal string snapshot and never changes, so tag comparison can't work either. Those configs use date-based pseudo-versioning (Release date as version plus Use the latest asset date as the release date) instead.

The config format​

An Obtainium app configuration is a flat JSON object. Four keys are required — id (Android package name), url (the GitHub repo, which is what selects the source), author, and name. Everything else goes in additionalSettings, a JSON string nested inside the JSON, so its quotes and backslashes are escaped one extra level. Any key you omit takes its default.

The same object travels in three shapes:

ShapeFormatUsed for
Import/export file{"apps":[…],"settings":null}Import/Export → Obtainium import
Deep linkobtainium://app/<percent-encoded JSON>one-tap add with settings baked in
Config-site entry{"configs":[…],"icon","categories","description"}PRs to apps.obtainium.imranr.dev

obtainium://add/<url> only prefills the Add-App page; obtainium://app/… is what carries settings. Wrapping a link as https://apps.obtainium.imranr.dev/redirect.html?r=obtainium://app/… keeps it clickable where a custom scheme wouldn't linkify.

Obtainium keys apps by package name, so the two stable flavors cannot coexist as separate entries — the config-site submission expresses them as alternate configs with an altLabel each. See obtainium/README.md for the full key reference and the submission checklist.

Notes​

  • Play Protect may interrupt the install with "App scan recommended — Play Protect hasn't seen this app before," offering Scan app or Don't install app. Scan app uploads the APK to Google. Declining cancels the install, so on a phone with Play Services you'll need to allow the scan, or install with adb install instead. This showed up for a debug-signed snapshot but not for a release-signed build.
  • Obtainium's first launch shows two full-screen dialogs (a welcome note and a Play-certification note). They swallow an incoming obtainium:// link, so dismiss them before using a one-tap link.
  • Track without installing: turn on Track-only to get update notifications without Obtainium downloading anything.
  • Snapshot filenames carry the versionCode so that a moving tag, which reuses the same release and asset URLs forever, still produces a distinguishable asset on every build.