PermuteDocs
Go to Permute

Build apps

Update and restore app releases

Resume shared source, publish updates, pin action revisions, and restore a reviewed earlier app build.

Before you start

Workflow

  1. 1Use an existing app and a management client with the permissions required by the change. Set PERMUTE_APP_ID, PERMUTE_WORKSPACE_ID, and PERMUTE_API_KEY.
  2. 2Run the read-only setup below. The following server-side snippets reuse client, appId, app, and required; choose the workflow you need.
  3. 3Review the exact draft and compiled build before publication. Reconcile concurrent changes instead of retrying a stale save or publication.

Example

typescript
import { PermuteClient } from '@permute/sdk';

function required(name: string): string {
  const value = process.env[name]?.trim();
  if (!value) throw new Error('Set ' + name);
  return value;
}
const client = new PermuteClient({
  apiKey: required('PERMUTE_API_KEY'),
}).withWorkspace(required('PERMUTE_WORKSPACE_ID'));
const appId = required('PERMUTE_APP_ID');
const app = await client.apps.get(appId);
console.log(await client.revisions.list(appId));

Checkpoint source and continue a teammate’s work

Invited editors can open App details and select Download source using their Permute session (no API key needed). Extract the ZIP: source/ contains the project, and app-source.json records its build instructions, exact revision and observed draft token. No project scripts run during download. SDK checkoutApp requires a separately granted API key; it retrieves draft or historical source into a new folder, verifies file hashes and never overwrites an existing folder. Keep the observed expectedDraft token when saving edits so concurrent work cannot be overwritten.

saveAppSource checkpoints source without publishing. deployApp saves source and compiled output together. A source change makes the previous build stale; publication requires a matching build. Build from the source you intend to save, keep the project unchanged while deploying, and preserve its lockfile and pinned runtime. The recorded pairing is declared by the uploader, not independently verified by a hosted builder.

The helper applies root and nested .gitignore rules to all local files, without requiring Git or commits. It retains visited .gitignore files and excludes build output, dependencies, credentials, caches and personal agent state; exceptions cannot override these exclusions. Keep shared instructions, skills, tests, lockfiles and setup scripts in the project. Internal symlinks become ordinary files, and executable scripts retain their executable bit. Source allows 1,000 files; compiled output allows 200. Both allow 4 MiB per file and 50 MiB total. Environment templates are allowed, but their contents must contain no secrets.

App admins can select Allow editing in Share; ordinary app viewers cannot retrieve source. The App page shows whether draft source is missing, uncompiled, or saved with a matching build. Checkout downloads project files without executing hooks or scripts.

typescript
import { checkoutApp, saveAppSource, deployApp } from '@permute/sdk/deploy';

const checkout = await checkoutApp(client, { appId: app.id, directory: './teammate-app' });
// Edit files in teammate-app. To checkpoint without publishing:
if (!checkout.expectedDraft) throw new Error('Review the current draft before saving');
const saved = await saveAppSource(client, {
  appId: app.id, expectedDraft: checkout.expectedDraft,
  source: { directory: './teammate-app', build: checkout.source.build },
});
// Run the stored build command in teammate-app, then publish its output:
await deployApp(client, {
  appId: app.id, directory: './teammate-app/' + checkout.source.build.outputDirectory,
  source: { directory: './teammate-app', build: checkout.source.build },
  expectedDraft: saved.draft,
});

What happens to files and versions

Uploading the same contents reuses the existing file. Changed contents at the same path are stored separately, and the new draft points that path to the new contents. Previous versions keep their original files.

Every save replaces the complete file list (the manifest), so include unchanged files too. A file omitted from the new manifest disappears from the live app when you publish. Uploading or saving alone never changes the live site.

Apps use the shared resource versioning system. App-specific save calls validate the files and advance the draft; revisions.list, revisions.get, revisions.restore, and revisions.publish provide history, revision reads, rollback, and publication. To review a draft before release, stop after saving and publish it separately.

expectedDraft and expectedVersion reject concurrent changes. On a 409 conflict, read the current draft and reconcile your build before trying again. Replacing an existing unpublished draft is an intentional edit; review it before saving.

Roll back a published app

Use the setup above to read the app and its revision history. Choose and review an earlier published revision, then set PERMUTE_ROLLBACK_REVISION_ID. The following snippet restores it as a draft and publishes only that exact restored draft.

Restore recovers source, build instructions, compiled files and settings together. Older compiled-only revisions retain their builds but have no recoverable source. Restoring alone leaves the live site unchanged. Previously published assets remain readable under current app permissions so pages already open can finish loading; unpublished drafts are not served.

typescript
const revisionId = required('PERMUTE_ROLLBACK_REVISION_ID');
const current = await client.revisions.list(appId);
const restored = await client.revisions.restore(appId, revisionId, { expectedVersion: current.version });
// Reject changes made after restore before publishing.
const ready = await client.revisions.list(appId);
if (ready.draft?.revisionId !== restored.draft?.revisionId || ready.version !== restored.version) {
  throw new Error('The draft changed; review before publishing');
}
await client.revisions.publish(appId, { expectedVersion: ready.version });
console.log('Published revision:', ready.draft?.revisionId);

Pin actions to an app release

Use this section only for apps that need Business Actions; query-only apps can skip it. Publish the action first, then include its exact revision pin when deploying. The snippet below reuses client, app, and required from the setup above. Run it from the frontend project with a current dist build.

Saving and publishing require invocation permission on each selected action. Omitting actions preserves the current bindings; passing [] clears them. The deployment helper publishes the saved revision with concurrency checks.

Before publishing, an app admin must approve resource grants on the app detail page or through the grants API. Approval also requires admin permission on each target. Grant Read for query sources and the action’s required invocation level for actions. Existing apps need this approval too; bindings alone no longer authorize app API calls.

Each app revision pins its action revisions. Publishing a new action does not silently change an existing app; update the binding and publish the app again to adopt it. Query access follows current app grants and user permissions; source grant changes take effect without republishing. SQL filters in browser code are not a row-level security boundary.

When replacing existing generic read actions, migrate every frontend caller to normal source/query APIs, publish the updated app without those action bindings, revoke their app grants, and delete the read action resources only after checking that no other callers use them. Keep explicitly requested write actions and their revision pins.

typescript
import { deployApp } from '@permute/sdk/deploy';

const actionId = required('PERMUTE_ACTION_ID');
const action = await client.actions.definition(actionId); // Requires View code on the action.
if (!action.published) throw new Error('Publish the action first');

await deployApp(client, {
  appId: app.id, directory: './dist', expectedDraft: app.draft,
  source: { directory: '.', build: {
    command: 'bun run build --base=./', outputDirectory: 'dist', runtime: 'bun@1.3.12',
  } },
  actions: [{ actionId, revisionId: action.published.revisionId }],
});

Verify the deployed app and its action revisions

Review the compiled build and the exact action revisions pinned by the app, not only local source or the latest action draft. Keep a release record of the app revision and its action pins. Publishing a corrected action alone does not update a pinned app release. Preserve existing login, branding, and access settings when saving a site update.

Inspect browser network requests during sign-in, initial load, filtering, history changes, and detail views. Bundle fonts, icons, and brand assets locally where possible; avoid third-party scripts, analytics, remote fonts, and URLs containing business data. Render source strings as text rather than HTML. Hosting restrictions are a safeguard, not a substitute for inspecting dependencies and the built artifact.

Verify that live screens use real source/query results or bound action outputs, according to their data contract, and contain no fallback demo records. Keep any preview fixtures outside the production build. Test the intended visitor permissions separately from an administrator authoring key. A loading spinner, a passed build, or an administrator-only test does not establish that ordinary visitors can read the deployed data safely.