Docs / Release operationsSDK downloadsGitHub ↗

SDK release operations

PushHub publishes client packages through a gated, reproducible release process. This document defines what automation proves, what still requires human evidence, and how to stage or roll back a release.

Release channels

Channel Automated evidence External evidence Intended use
Preview Package shape, source contracts, artifact integrity Editor/device smoke testing in progress Development evaluation
Beta Compiling native core, unit and contract suites, immutable artifact Controlled provider and physical-device rollout Limited production
Stable Every Beta gate plus signing, licensed engine matrices, and stored physical-device evidence Release owner approval General production

The public manifest is authoritative. A package must not be described as Stable unless scripts/verify-sdk-compatibility.mjs passes with PUSHHUB_STABLE_GATE=approved.

Continuous compatibility matrix

.github/workflows/sdk-ci.yml runs on SDK and documentation changes. It verifies:

  • JavaScript on active Node 18, 20, and 22 runtimes;
  • Android against the minimum API 23 and current API 35 toolchains;
  • the root and nested Swift packages with Swift 5.9 on the macOS 14 compatibility runner and the current Xcode Swift 6 toolchain;
  • Flutter analysis and unit tests on stable Flutter;
  • React Native type declarations, CommonJS/ESM builds, and package contents;
  • required Unity, Unreal Engine, and Godot adapter surfaces;
  • artifact byte sizes, SHA-256 values, compatibility metadata, search output, and developer-hub routes.

Licensed Unity, Unreal Engine, and Godot editor runners are an explicit Stable gate. Their repository variable must remain false until the matrix results are retained with the release record.

Protected release environment

Create a GitHub environment named sdk-release with required reviewers. Stable promotion also requires:

  • APPLE_SIGNING_CERTIFICATE secret;
  • ANDROID_SIGNING_KEYSTORE secret;
  • LICENSED_ENGINE_RUNNERS_READY=true repository variable;
  • DEVICE_MATRIX_EVIDENCE repository variable containing the retained test-run reference.

Run Publish SDK release only for an existing, annotated tag. The workflow verifies the checked-out tag, stages only recorded artifacts, creates a GitHub artifact attestation, and publishes a GitHub release. Preview and Beta releases are always marked prerelease.

Staged rollout

  1. Publish the immutable artifact without changing its public channel.
  2. Use an internal app and a dedicated PushHub app configuration for provider smoke tests.
  3. Roll out to a small production cohort and watch registration, provider acceptance, receipt, open, and retry-error rates.
  4. Expand only while the client and provider error budgets remain green.
  5. Record physical-device and engine evidence before requesting Stable promotion.

Run node scripts/verify-production.mjs after every deployment. It verifies the API, page identity for all four public surfaces, the production release manifest, and every downloadable artifact.

Rollback

SDK packages are immutable and are never overwritten. Stop promotion, deprecate the affected version in the manifest, and direct clients to the previous known-good version. Server changes remain backward compatible for the published minimum backend contract date. If a web deployment fails, restore the previous image tag and reload the shared edge proxy; do not delete already published SDK artifacts.