The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
description: How OpenHuman ships a release, with the branch model, CI lanes, minimum-version gate and key rotation. icon: ship
Release policy
This runbook covers how releases ship. It also explains how we stop users from completing OAuth (including Gmail) on an outdated desktop installer when the latest release is the supported flow.
Distribution
- GitHub Releases for tinyhumansai/openhuman are the primary source for desktop builds.
- The Tauri updater endpoint (see
scripts/prepareTauriConfig.jsand the release workflows) should point users at the current release artifacts. - To retire old stable artifacts when you drop a release line:
- Remove or hide the obsolete installer assets on GitHub Releases.
- Point website and CDN download links at
releases/latest. - Refresh the updater manifest (for example a Gist or
latest.json) so it does not point at deprecated builds. - Check that old direct URLs redirect or return 404 or 410. Try known-old asset URLs from docs or bookmarks and confirm they no longer deliver a primary install path.
Minimum app version for OAuth
Production web builds embed a minimum supported app version at build time, so OAuth deep links cannot complete on deprecated binaries. Each installer carries the floor that was set when that build was made. Raising the floor for users who never upgrade needs a new release that they install, or an in-app update.
| Variable | Purpose |
|---|---|
VITE_MINIMUM_SUPPORTED_APP_VERSION |
For example 0.51.0. The desktop app must be at least this version to finish openhuman://oauth/success. |
VITE_LATEST_APP_DOWNLOAD_URL |
Optional; defaults to https://github.com/tinyhumansai/openhuman/releases/latest. Opened when the gate blocks OAuth. |
Configure these as GitHub Actions variables. Set them on both the standalone pnpm build step and the tauri-apps/tauri-action step in .github/workflows/build-desktop.yml (the reusable matrix that release-production.yml and release-staging.yml call), so the Vite bundle in shipped installers includes the gate. Leave VITE_MINIMUM_SUPPORTED_APP_VERSION unset for local development, which disables the gate.
The code is in app/src/utils/oauthAppVersionGate.ts, app/src/utils/desktopDeepLinkListener.ts.
Gmail / Google Cloud OAuth
- Redirect URIs in Google Cloud Console must match the current backend + tunnel callback paths.
- The desktop scheme (
openhuman://) is stable. WhenVITE_MINIMUM_SUPPORTED_APP_VERSIONis set, the installed binary must meet the minimum version.
Release checklist
- Bump
app/package.jsonandcrates/openhuman-app/tauri.conf.json(and rootCargo.toml/ core) per existing version workflows. - When dropping support for older installs, set
VITE_MINIMUM_SUPPORTED_APP_VERSIONto the new floor before or with that release (repo Actions variables + both workflow steps above). - Remove, redirect, or retire older stable installers and stale updater entries from user-facing surfaces (GitHub Release assets, website, CDN, updater feed). Confirm deprecated artifacts are not reachable from default install/update flows.
- Smoke-test Gmail connect on a fresh install from releases/latest.
- Complete the manual smoke checklist. Then paste the completed sign-off block, verbatim with every checked item left checked, as a GitHub commit comment on the
v<version>-stagingtagged commit that QA validated. The promotion flow has no release PR. Before approving the production run, theRelease-Approvalreviewer checks two things. First, the sign-off comment exists on the staging-tagged commit. Second, the production run targets that validated content: either pass the staging-tagged SHA ascommit_sha, or confirm that only[skip ci]version-bump commits separate it from the run's target. Anything more is new content QA never smoked, so re-run staging first.
Branch model and CI lanes
Two long-lived branches, two CI lanes:
main: where all feature and fix PRs land. Every PR runs CI Fast (ci-fast.yml), with quality checks and full unit-test suites for changed areas, gated at 80% diff coverage or more.release: a maintainer-promoted snapshot ofmainthat releases are cut from. PRs targetingreleaseand every push toreleaserun CI Full (ci-full.yml): complete unit suites, Rust mock-backend E2E, Playwright web E2E, and desktop E2E on Linux. macOS and Windows desktop E2E are manual dispatches that default to off until a native driver exists for each, so cross-platform desktop signal is opt-in. TheCI Full Gatecheck aggregates every lane except the Playwright spec run. That run is non-blocking for now (continue-on-error, because it is flaky under CI contention), so a green gate does not prove the Playwright specs passed. Check that lane's result before cutting. Only the Playwright artifact build is gated.
The cycle:
- A maintainer dispatches
promote-main-to-release.yml, which pushes a merge commit frommainintoreleasewith no PR. Re-dispatching refreshesreleasewith the latestmainand keeps fix commits already onrelease. Ifreleasealready containsmain, it does nothing. - CI Full runs on the promotion push. If it finds breakage, anyone with write access opens a fix PR directly against
release. Fix PRs run both lanes: CI Fast for quick lint and coverage feedback, and CI Full as the merge-blockingCI Full Gatecheck. The post-merge push re-runs CI Full on the merge result. - Once CI Full is green on
releaseHEAD, cut production withrelease-production.yml. You can dispatch staging frommaininstead when QA needs to validatemainbefore promotion. The release workflows do not check theCI Full Gate, so operators must verify the CI evidence before cutting. - A cut from
releaseback-mergesreleaseintomainwithscripts/release/merge-release-into-main.sh. It fast-forwards when it can, and otherwise makes a versioned merge commit such aschore(release): merge release v1.2.4 back into main. Bump and fix commits flow back that way. A staging cut frommainneeds no back-merge. Version-bump commits carry[skip ci].
Required GitHub settings for this model (repo Settings > Rules): main requires the PR CI Gate status check on PRs; release requires PRs for non-bypass actors with the CI Full Gate status check required (it runs on PRs targeting release); the release GitHub App is on the bypass list of both rulesets so the promote and release workflows can push directly.
Workflows: staging and production
There is one GitHub Actions workflow per environment. Pick by intent instead of toggling a flag. Staging follows the selected main or release dispatch ref; production always checks out release, regardless of the dispatch ref shown by GitHub's workflow UI.
| Workflow | Branch | Bumps | Tags pushed | Concurrency group | Use when |
|---|---|---|---|---|---|
release-staging.yml |
main or release |
patch only |
v<version>-staging |
release-staging |
Cutting a staging build for QA from the selected branch. |
release-production.yml |
release |
patch / minor / major (release_type input) |
v<version> |
release-production |
Shipping a production release from validated release HEAD (or a pinned commit_sha). |
The build, sign, Sentry debug-file and artifact-upload pipeline that both flows use lives in .github/workflows/build-desktop.yml as a reusable workflow_call workflow. The two workflows above own ref resolution, version bumping, tagging, and publish and cleanup. The build itself is shared.
Android / Google Play
Android releases are handled by the separate .github/workflows/android-compile.yml workflow. It builds a release Android App Bundle (.aab), signs it with the Play upload key, and uploads it to Google Play when publishing is enabled. The unsigned and signed AABs stay as Actions artifacts for audit and debugging.
Manual Android uploads use the same workflow:
pnpm --dir app release:android:play -- --track internal
pnpm --dir app release:android:play -- --ref main --track production --status draft
Required GitHub Actions secrets:
| Secret | Purpose |
|---|---|
ANDROID_UPLOAD_KEYSTORE_BASE64 |
Base64-encoded Play upload keystore (.jks). Use the upload key, not the Google app signing key. |
ANDROID_UPLOAD_KEY_ALIAS |
Keystore alias for the upload key. |
ANDROID_UPLOAD_KEYSTORE_PASSWORD |
Keystore password. |
ANDROID_UPLOAD_KEY_PASSWORD |
Key password. |
GOOGLE_PLAY_SERVICE_ACCOUNT_JSON |
Raw JSON for the Play Console service account with release permissions for com.openhuman.app. |
Optional GitHub Actions variables:
| Variable | Default | Purpose |
|---|---|---|
ANDROID_PLAY_TRACK |
internal |
Play track to upload to (internal, alpha, beta, or production). |
ANDROID_PLAY_STATUS |
completed |
Play release status (completed, draft, inProgress, halted). |
Google Play requires each upload to use a higher Android versionCode than the last. The release bump scripts update app/src-tauri-mobile/tauri.conf.json, app/src-tauri-mobile/Cargo.toml and app/src-tauri-mobile/Cargo.lock with the desktop files, so the generated Android tauri.properties moves with each release.
Cutting a staging build
- Run Release (Staging) via
workflow_dispatchfromrelease(optionally pinning a release-reachablecommit_sha).create_tag = falsebumps and commits without tagging or building. - The workflow bumps
patchonrelease, commitschore(staging): vX.Y.Z [skip ci], pushes, and creates an immutablevX.Y.Z-stagingtag at that commit. - The build matrix runs from the tag, not
releaseHEAD, so reruns rebuild identical content even ifreleasehas moved on. - The bump commit (and anything else on
release) is merged back intomain. - On failure the staging tag is deleted automatically. The bump commit on
releasestays, so the next cut continues fromvX.Y.(Z+1).
There is no separate staging branch. Staging cuts and production releases both live on release, and only the tag suffix (-staging or none) and the workflow that made the tag tell them apart.
Shipping a production release
- Run Release Production via
workflow_dispatchwith the desiredrelease_type(patch/minor/major), fromreleaseHEAD or a pinned release-reachablecommit_sha. - The run first waits on the
review-approvaljob (environment: Release-Approval). A required reviewer must approve before anything is pushed. Thenprepare-buildbumps the version onrelease, commitschore(release): vX.Y.Z [skip ci], pushes, tagsvX.Y.Z, builds and publishes. releaseis merged back intomainright after the cut.
Tag policy and rollback
- Naming: staging tags use the SemVer pre-release suffix
-staging(v1.2.4-staging), so they sort before the matching production tag. - Collisions: both workflows fail fast if the target tag already exists locally or on
origin. Delete the stale tag (org maintainers only) or bump past it. - Production rollback: a failed build matrix triggers
cleanup-failed-release, which deletes the draft GitHub Release and thev<version>tag. - Staging rollback: a failed staging build deletes the
v<version>-stagingtag. The bump commit on the source branch stays. The next staging cut continues from the new patch number, which leaves a small gap in patch numbers instead of racing concurrent merges. - Deleting tags: you need the same write access as
main. Workflow cleanup runs with the workflow's token throughactions/github-script. The GitHub App token is used only byprepare-buildfor the bump commit and tag push. Manual deletes (git push --delete origin <tag>) need equivalent maintainer permissions.
Release App token: approval gate and rotation
release-production.yml bumps the version, commits to release and back-merges into main, pushing those commits and the tag with a GitHub App token (secrets.XGITHUB_APP_ID / secrets.XGITHUB_APP_PRIVATE_KEY) that bypasses branch protection. The same App pushes staging bumps to the selected main or release source (release-staging.yml) and promotion merge commits (promote-main-to-release.yml). A leaked private key (through a log, a compromised action or a misconfigured runner) would let an attacker push arbitrary commits to protected branches (CWE-250). Two controls limit the damage.
Manual approval gate
The review-approval job runs before prepare-build and parks every production run on the Release-Approval GitHub environment, so a human must approve before any push happens.
One-time setup (repo Settings > Environments):
- Create an environment named
Release-Approval(the exact name, because the workflow references it verbatim). - Under Deployment protection rules, enable Required reviewers and add the maintainers allowed to authorize a production push to
main. A reviewer cannot approve their own run unless Prevent self-review is off. For a release gate, keep it on so a second person approves. - Optionally set the wait timer to 0. The gate is a human decision, not a delay.
When a production run starts, the review-approval job shows "Waiting". An approver opens the run and clicks Review deployments > Approve. Rejecting or cancelling skips prepare-build, so nothing is pushed.
Quarterly key rotation
Rotate XGITHUB_APP_PRIVATE_KEY every quarter (and immediately on any suspected exposure). Do it at the end of March, June, September and December.
- In the GitHub App settings (Org > Settings > Developer settings > GitHub Apps > the release App), under Private keys click Generate a private key. Download the new
.pem. - Update the repo secret: Settings > Secrets and variables > Actions >
XGITHUB_APP_PRIVATE_KEY, then paste the full new key (including the-----BEGIN/END-----lines).XGITHUB_APP_IDis unchanged. - Trigger a low-risk verification run, such as Release (Staging), and confirm the Generate GitHub App token step succeeds and the push authenticates. Do not use Release Production for this unless you mean to cut a real bump commit. Even with
create_release = false,prepare-buildstill bumps the version and commits torelease. Staging withcreate_tag = falsealso commits but skips the tag and build, so it is the lower-risk probe. - Back in the App settings under Private keys, delete the old key so only the freshly-issued one remains valid.
- Record the rotation date in the PR description or the ops log so the next owner can see when it last happened.
Rotating invalidates any leaked copy of the old key, which caps the exposure window at one quarter.