Version Channels

Stage apps support deployment channels that control which version of your app is served in each environment. Channels let you promote tested versions from preview to production and roll back if needed.

Channel Model

Each app can have two channels:

Channel	Purpose
preview	Latest development version, used for testing and review
production	Stable version served to end users

A channel record pins a specific app version to an environment. When you deploy, the preview channel is updated automatically. Production requires an explicit promotion step.

Data Model

interface AppChannel {
  appSid: string;           // Parent app ID
  channel: "preview" | "production";
  appVersionSid: string;    // Pinned version ID
  sessionId: string;        // Session backing this version
  branch?: string;          // Git branch at deploy time
  commitSha?: string;       // Git commit at deploy time
  updatedByEmail: string;   // Who last updated this channel
  updatedAt: number;        // Unix timestamp (ms)
}

Version Sources

Versions can originate from different workflows:

Source	Description
publish	Initial app publication
studio_deploy	Deploy from Studio session
feedback	Iteration based on user feedback
promotion	Promoted from another channel

Workflow

Studio Deploy → preview channel → (promote) → production channel
                    ↑                              ↓
                 rollback ←─────────────────── rollback

1. Deploy — Push files and trigger render. The preview channel auto-updates.
2. Test — Validate via the preview URL or delegated agent tests.
3. Promote — Move the preview version to production.
4. Rollback — Revert production to a previous version if needed.

Convex Operations

Operation	Function	Description
Get channel	stage:getResolvedAppChannel	Retrieve channel record with linked version details
Upsert channel	stage:upsertAppChannel	Create or update a channel with a new version
Get summary	stage:getAppChannelsForSummary	Fetch both channels for an app in parallel

Channel-Scoped Configuration

Each channel maintains its own:

• OAuth configuration — Scopes and client settings can differ between preview and production
• Session binding — Each channel points to a specific session with its own file state
• Git tracking — Branch and commit SHA recorded at deploy time for traceability

Storage

Channel records are stored in the stage_app_channels Convex table with a composite index on (appSid, channel) for fast lookups.