PatchForge
Sign inStart free

Get started / Using the dashboard

PatchForge How-To Guide

Task-oriented instructions for the everyday workflows in the PatchForge dashboard. For definitions of the entities mentioned here (applications, channels, releases, rings, rollouts, deployments, patches, health scores, devices), see concepts.

Throughout this guide, actions you don't have permission for are hidden or disabled. If you can't see a button mentioned below, ask an organization admin to grant the relevant role.

1. Create an application

  1. From the sidebar, open Applications.
  2. Click New App (the create button on the Applications listing).
  3. Fill in the form:
    • Name — a human-readable name for the app.
    • Description (optional).
    • Android package name and/or iOS bundle identifier — in reverse-DNS form, e.g. com.company.app. You must provide at least one platform identifier; you can provide both.
  4. Submit. You are taken to the new application's detail page.
  5. On the application page, note the appKey — the public identifier your React Native SDK uses to talk to the OTA server. Copy it into your SDK configuration. It is not a secret and is safe to embed in your shipped binary.

PatchForge automatically creates a set of default channels (environments) for the new app. You can manage them under the application's Settings → Channels (rename, set the default, add/edit).

2. Upload a release

  1. Open the application, then go to Releases → New Release.
  2. In the wizard:
    • Choose the channel (environment) this release targets. The store version, bundle version, and release name are prefilled from the channel's latest release (the bundle version auto-increments); edit them if this release starts a new store version.
    • Select the bundle artifact — the raw JS bundle (index.android.bundle / main.jsbundle), or with SDK ≥ 0.2.7 a .zip of index.<platform>.bundle plus Metro asset folders (ships images/fonts OTA and enables differential patches).
    • Acknowledge the OTA compliance notice — you may ship JavaScript and assets only, never native binaries or executable code. The required acknowledgement checkbox must be ticked before you can submit.
  3. Submit. The release is created and the bundle is uploaded; the release status moves to Uploaded, then a background worker takes it to Processing.
  4. Wait for Ready. During processing the platform hashes the bundle, signs it (RSA-4096), and builds the manifest. When that succeeds the status becomes Ready and the release is deployable. If it instead becomes Failed, open the release detail page to read the failure reason.

You can watch the release status on the application's Releases listing or the release detail page. The release detail page also shows the release's files and a signature card.

A Ready release is not yet live on any device — it must be deployed (next step). After a release is Ready, the server also begins generating patches from recent prior releases automatically (visible under the application's Patches view).

3. Deploy a release

  1. Open the Ready release's detail page (or work from the Deployments area).
  2. Click Deploy. In the deploy dialog:
    • Ring — choose the audience segment: Internal, Beta, Early Access, or Production.
    • Rollout % — choose what fraction of eligible devices receive the update: 1, 5, 10, 25, 50, 75, or 100%.
    • Notes (optional) — reason or context for the deployment.
    • Production safety gate — if the target channel is a Production environment, you must type the exact bundle version to confirm before the Deploy button enables.
  3. Confirm. The release becomes the channel's Active deployment (superseding any previous active deployment on that channel).
  4. Monitor the deployment timeline. On the deployment detail page you'll see a GitHub-Actions-style timeline of events (created, validated, signed, patch generated, deployed). Devices in the rollout bucket begin receiving the update on their next check.
  5. Widen the rollout over time: on the deployment detail page, adjust the rollout percentage upward as the release proves healthy. Use the release health card (and the per-channel environment-health cards on the application page) to judge whether to widen or hold.

4. Roll back a deployment

If a deployment is causing problems, roll it back to restore the previous release:

  1. Open the active deployment (from the release detail page or the Deployments area).
  2. Click Rollback. In the rollback dialog:
    • Reason (optional) — e.g. "Crash increase detected".
    • Confirmation — type ROLLBACK to enable the button. This re-activates the previously deployed release at 100% on the channel.
  3. Confirm. The current deployment is marked RolledBack and the previous release becomes active again.
  4. On the device side, the SDK pulls the previous bundle on its next update check. (Independently, the on-device SDK also has its own crash-loop protection that reverts to the last known-good bundle without dashboard action.)

5. Dashboard tour

The dashboard is organized around a left sidebar and a top topbar.

Home (/) — the landing page shows:

  • KPI cards — at-a-glance metrics such as active devices and recent deployments.
  • OTA trend chart — deployment/rollback activity over time.

Sidebar navigation:

SectionWhat it's for
DashboardThe home overview (KPIs + OTA trend).
ApplicationsYour registered apps; create apps, manage channels, releases, patches, deployments, devices.
DeploymentsOrganization-wide feed of deployments across all apps.
AnalyticsOperational analytics — KPIs, OTA trend, recent crashes.
DevicesOrganization-wide read-only feed of devices and install history.
NotificationsThe full in-app notification feed.
OperationsJob monitoring + system settings (visible to operators only).
SettingsProfile, security/MFA, API keys, users, system settings, feature flags.

Topbar — holds the current organization badge, the command palette / search trigger (see below), a notifications bell, the theme toggle (dark default, light available), and your user menu (with sign-out).

6. Command palette (⌘K)

The command palette is the fastest way to jump anywhere.

  • Open it with ⌘K (macOS) or Ctrl+K (Windows/Linux). You can also press / when no input is focused, or click the Search… button in the topbar.
  • With the palette open and empty, it lists quick Navigation entries (Dashboard, Applications, Deployments, Analytics, Devices, Notifications, Settings, Operations).
  • Type at least two characters to search. Results are grouped by Applications, Releases, Deployments, Devices, and Users.
  • Select any result (or navigation entry) to jump straight to it.

Search is scoped to your current organization and your permissions (see Global search below).

7. Personal access tokens (PAT) / automation

  1. Go to Settings → API Keys.
  2. Click to create a new personal access token (PAT). The token value is shown once at creation — copy and store it securely; you cannot retrieve it again.
  3. Manage existing tokens (view metadata, revoke) from the same page.

Note: PATs are intended to authenticate the future REST automation API (/api/v1), which is deferred in this release. Generating the token in the dashboard is the step you can do today; the public REST automation surface (and the CLI that consumes it) ships later. PATs are not used for the device-facing /api/sdk/* OTA endpoints — those authenticate with the app's appKey and signed download tokens.

8. Maintenance mode

Maintenance mode safely pauses operator-side changes during maintenance windows, without disrupting devices.

  1. Go to Settings → System (under Operations / settings, requires the settings.manage permission).
  2. Enable Maintenance Mode (you can also configure a platform announcement here).
  3. A global banner appears across the dashboard for all users.

While maintenance mode is on:

  • Mutating operations are blocked — deploying, rolling back, creating releases, and application/channel mutations are gated. (Turning maintenance mode off is, of course, exempt.)
  • Device-facing OTA traffic is unaffected. The /api/sdk/* endpoints (check, download, reports, heartbeat) keep serving devices normally. Maintenance mode is an operator-side write gate, not a device outage.

9. Notifications

PatchForge surfaces in-app, organization-wide notifications for significant events.

  • The bell icon in the topbar shows recent notifications. Notifications are emitted org-wide on events such as deploy and rollback.
  • Click the bell, or open Notifications from the sidebar (/notifications), to see the full feed.
  • Any member can view notifications. (Additional external delivery channels such as email or webhooks are not part of this release.)

Global search lets you find apps, releases, deployments, devices, and users quickly.

  • Use the command palette (⌘K / Ctrl+K) or the topbar Search… button.
  • Type at least two characters; results stream in, grouped by entity type (Applications, Releases, Deployments, Devices, Users).
  • Search is scoped to your current organization and to your permissions — you only see results you are allowed to see.
  • Select a result to navigate to it instantly.