Source Control

Source control lets Second store app source in a repository instead of treating MongoDB as the authoritative code store. MongoDB still stores app metadata, run history, audit data, and a materialized snapshot/cache so preview stays fast. For source-control-backed apps, the code source of truth is the repository. Supported providers include GitHub, GitLab, Bitbucket, and self-hosted source control in enterprise deployments.

Mental model

There are three separate concepts:

Concept	Meaning
Source-control connection	Workspace credentials and target owner exist. Nothing is uploaded just because this exists.
Source storage policy	On-prem/managed setting that makes successful builds write app source to source control after `done_building`.
Available Apps	Optional discovery/install layer for apps intentionally shared with local CLI/desktop users.

Connecting source control only enables the feature. It does not upload apps. In local CLI/desktop mode, source-control storage is app-level: a builder turns on Publish to source control for a specific app from the app top bar. In on-prem or managed deployments, admins can turn on Store app source in source control in Settings -> Source Control. When that workspace-level storage policy is on, successful done_building snapshots are committed to the configured provider automatically. Existing Mongo-only apps are adopted the next time a successful build creates a new app snapshot. Available Apps is separate. A source-control-backed app can be stored in a repository without being listed as an Available App.

What gets loaded from where

App viewing and agent source restore are different paths. The app page must be fast. It renders the built artifact from the saved snapshot/cache. It does not download source from source control and it does not compile on page load. Agent restore is different. If a worker/container/local session is still alive, Second keeps using the live files already on disk. If the session died and the app is source-control-backed, Second restores source from source control, then caches that restored snapshot back into MongoDB.

Deployment	Source control	App preview/page	Agent files when session is alive	Agent files when restore is needed
Local CLI/desktop	Off	Mongo snapshot is authoritative.	Live local worker files.	Mongo snapshot.
Local CLI/desktop	On for that app	Source control is authoritative. Render the cached built artifact for the selected repository version.	Live local worker files.	Source control, then cache in Mongo.
On-prem/cloud	Off	Mongo snapshot is authoritative.	Live container files.	Mongo snapshot.
On-prem/cloud	Workspace source storage on	Source control is authoritative. Render the cached built artifact for the selected repository version.	Live container files.	Source control, then cache in Mongo.

The important rule:

App preview/page = saved built artifact/cache.
Source restore for a dead session = source control when that app is source-control-backed.
If the session is still alive, no restore is needed.
If the app is not source-control-backed, Mongo remains authoritative.

MongoDB is still used in source-control mode, but it is a materialized cache for fast app rendering and recovery. It is not the source of truth for a source-control-backed app.

Source storage modes

Local CLI/desktop

Local installs use app-level opt-in. The app top bar shows Publish to source control only when:

workspace source control is connected,
the user can edit the app,
the user is looking at the draft app.

The first publish takes the current app state from live worker files when available, otherwise from the saved Mongo snapshot. Second then:

Creates a repository if the app does not already have one.
Writes the sanitized app files.
Writes root second-app.json.
Best-effort adds the second-app repository topic.
Commits the snapshot.
Creates second-app-v1.
Stores compact source-control metadata on the app document.

Apps that are not published stay local. done_building continues to save the snapshot locally, but it does not create a repo, commit, or tag.

On-prem and managed deployments

On-prem and managed deployments can use a workspace-level storage policy: Store app source in source control. When this setting is off:

MongoDB is authoritative for app source.
done_building saves snapshots as it does today.
The source-control connection exists only for explicit features that use it.

When this setting is on:

successful done_building saves the local snapshot/cache first,
then commits the sanitized app source to the configured provider,
creates or updates the app’s repository,
creates an auto-bumped second-app-v<N> tag when source changed,
marks source control as the authoritative app source.

This does not automatically list the app in Available Apps. Storage and distribution are separate.

Builds and versions

done_building remains the build gate. The worker runs the build, requires dist/index.html, collects the snapshot, and returns the successful build summary. The web route saves that snapshot first. Only after the snapshot is saved does Second try to sync to source control. Versioning is automatic:

First source-control-backed snapshot creates second-app-v1.
Each later successful build with changed source creates the next second-app-v<N> tag.
If the source hash did not change, Second does not create a duplicate version.
Tag messages use the successful done_building summary.
If source-control sync fails after local save, the app remains usable locally and the app source-control status shows the failure with a retry path.

Repository shape

A source-control-backed app repository contains:

generated app source files,
the built dist/** output from the successful build snapshot,
root second-app.json.

The manifest makes the repository self-describing:

{
  "type": "second.app.export.v1",
  "schemaVersion": 1,
  "app": {
    "name": "Customer Console"
  },
  "source": {
    "fileCount": 42,
    "totalBytes": 812345,
    "hash": "sha256:..."
  },
  "sourceControl": {
    "provider": "github",
    "owner": "acme",
    "repo": "second-app-customer-console",
    "tag": "second-app-v12",
    "version": 12,
    "commitSha": "...",
    "availableInCatalog": false
  }
}

The repository must not contain secrets or local runtime state. Source-control sync uses the same app-bundle filters that exclude unsafe files such as .env, .npmrc, .git, node_modules, local caches, and other non-app artifacts.

Available Apps

Local CLI/desktop users can open Available Apps from the workspace sidebar. The page reads the configured source-control owner and lists repositories that contain a valid root second-app.json and are marked as available in the manifest. The repository topic second-app speeds up discovery, but the manifest is the authority. Actions:

Action	Behavior
Get	Downloads the selected repository archive server-side, imports it as a local app, and records `installedFrom` metadata.
Update	Downloads the newer upstream version and updates the existing installed app from the same owner/repo.
Open	Opens an already installed local copy.

Installing from Available Apps creates a local copy. It does not turn on Publish to source control for that app. The app can still be published later, but that remains an explicit app-level action. Storage-only repos created by the on-prem workspace source storage policy are not listed in Available Apps unless a future sharing policy marks them discoverable.

Provider connection

Owners/admins configure source control from Settings -> Source Control. Enterprise deployments can use supported providers such as GitHub, GitLab, Bitbucket, or self-hosted source control. When the provider uses personal access tokens, prefer a fine-grained token owned by the user or organization that will hold app repositories. Recommended permissions:

Permission	Why
Metadata: read	Validate and discover repositories.
Contents: read/write	Read manifests, commit app snapshots, and download archives.
Administration: write	Create repositories and manage repository topics.

For GitHub fine-grained tokens, use the GitHub UI like this:

Resource owner: the user or organization that will own app repositories.
Repository access: choose All repositories for normal Second-managed source storage, because new app repositories are created over time.
Add permissions: stay on the Repositories tab and add Administration read/write plus Contents read/write.

Classic PAT fallback:

repo for private repositories.
public_repo only for explicitly public app repositories.

Repository visibility defaults to private. User-owned repositories must be owned by the authenticated provider account. For organization-owned repositories, configure the organization owner. Repo name prefix is optional. When it is blank, new repositories use second-app-<app-name>, for example second-app-customer-console. When a prefix is configured, new repositories use <prefix>-<app-name>.

Secret handling

The PAT is stored only through Second’s server-side secret store:

WorkOS Vault when configured,
encrypted local storage otherwise.

The token value is never returned to:

the browser,
the worker,
agent runtimes,
realtime events,
audit metadata,
logs.

Provider errors are normalized and redacted before they are shown to the user or stored on app metadata.

Tenant isolation

Source-control records are workspace-scoped. Every query includes workspaceId. Install, update, publish, and restore routes prove workspace/app access before mutating app files. GET/read paths do not create repos, sync snapshots, restore files, or write audit events. Provider calls that mutate state happen only from explicit mutation paths such as settings save, app publish, post-build sync, Available Apps install/update, or worker/session restore. Realtime events remain compact invalidation hints. They do not include source files, prompts, provider responses, tokens, cookies, headers, or full database documents.

App Preview: build artifacts, iframe rendering, and restore boundaries
App Governance: draft/published snapshots and review flow
Self-hosting: deployment and secret-store setup
Guard and Tenancy: workspace isolation and route guards

Getting Started

Architecture

Deployment

Community

Source Control

Mental model

What gets loaded from where

Source storage modes

Local CLI/desktop

On-prem and managed deployments

Builds and versions

Repository shape

Available Apps

Provider connection

Secret handling

Tenant isolation

​Mental model

​What gets loaded from where

​Source storage modes

​Local CLI/desktop

​On-prem and managed deployments

​Builds and versions

​Repository shape

​Available Apps

​Provider connection

​Secret handling

​Tenant isolation

​Related pages

Mental model

What gets loaded from where

Source storage modes

Local CLI/desktop

On-prem and managed deployments

Builds and versions

Repository shape

Available Apps

Provider connection

Secret handling

Tenant isolation

Related pages