Publishing

The platform loads apps from a source: a location it reads app folders from. You publish by placing your app folder in a source. A global admin registers the source once and syncs it; an organization admin then decides who can use each app. The admin steps are described in Administration.

Package the folder

Each app is one folder containing its manifest, artifact, and optional icon:

apps/
└── notes/
    ├── manifest.json
    ├── app.html
    └── icon.svg

The folder name is arbitrary — the platform identifies an app by the appId in its manifest.json. Remember the artifact must be a single file of at most 10 MB.

An app version is the pair appId + version. To keep several versions available at the same time (an organization can be pinned to one), keep one folder per version:

apps/
├── notes-1.0.0/
└── notes-1.1.0/

The same appId + version must not appear in two folders; both are skipped. An appId belongs to the first source that published it — another source declaring the same appId is ignored.

S3 sources

An S3 source is a bucket plus a prefix. Every folder below the prefix that contains a manifest.json becomes an app, at any depth:

s3://my-bucket/apps/notes/manifest.json      →  prefix "apps"
s3://my-bucket/apps/notes/app.html

Upload with any S3 client, for example the AWS CLI:

aws s3 sync publish/ s3://my-bucket/apps/ --delete
# S3-compatible storage: add --endpoint-url https://s3.example.com

Requirements:

• A prefix is mandatory; the bucket root cannot be a source.
• For an external bucket the admin enters the endpoint, region, bucket and an access key. The key needs to list the bucket and read objects under the prefix (s3:ListBucket, s3:GetObject); it never writes.
• The endpoint must be an https:// URL on a publicly resolvable host. Private addresses, localhost and plain http:// are rejected.
• At most 10,000 objects may live under the prefix; beyond that the sync refuses to run rather than publish a partial catalog. Keep build leftovers out of the prefix.

A source can also read from the platform's own storage (no endpoint or credentials), which is how first-party apps are shipped.

GitHub sources

Reading app folders from a GitHub repository, with a webhook that re-syncs on push, is implemented on the platform but not yet selectable in the admin interface ("Coming soon"). Use an S3 source until it is enabled.

Syncing

Nothing happens on upload. A source is read when a global admin chooses Sync now; S3 sources are not synced on a schedule. Each sync:

1. lists the folders and validates every manifest.json (rules),
2. copies the artifact and icon of each valid app into the platform,
3. publishes the valid apps, and unpublishes apps and versions that are no longer found — together with the scope approvals and version pins that organizations had set for a removed app.

An app that fails validation is skipped. If it was published before, skipping it means it is no longer found, so a broken manifest takes a live app offline on the next sync. As a safeguard, a sync that finds no valid app at all, while the source currently publishes some, is refused entirely.

The admin interface reports only how many apps were skipped, not why. Check a manifest against the validation rules before uploading; the most common causes are listed there.

Updating an app

Ship changes by bumping version in the manifest, replacing the artifact, and asking for a re-sync. Organizations that follow Latest move to the highest version immediately; organizations pinned to a version stay on it as long as that version's folder is still in the source. If a pinned version disappears from the source, the app stops being available to that organization until its pin is changed.

Two things to know before you bump:

• The key/value store is scoped to the app version. Users start with an empty store on every new version — migrate anything that must survive into the workspace.
• Re-syncing an unchanged version with a different artifact overwrites that version in place. That is convenient while testing, but give real releases a new version so pinned organizations get what they pinned.

Users do not need to reinstall after an update unless the major sdkVersion changes.