Changes
A change is how an edit to the company’s repository goes live once the repository has a remote (origin): an agent’s draft, reviewed and published in the app. Without a remote there is no change: saving is publishing.
- The draft. A chat’s edits are commits on the branch
draft/<id>(the chat’s id), in a checkout of its own under.sanoma/drafts/<id>(thesanomapackage’slocalGitSource), never the live one. The chat’s card lists the files and the result ofsanoma checkon the draft, and offers Save to the company and, with a remote, Review, once something is committed and the checks pass. - Save starts the built-in
save-draftworkflow on the draft, as the chat’s person (SanomaClient.saveDraft({ id, title, head?, page? }, { startedBy }); the run issave:<id>, andsave:<id>~2once that one has ended;SanomaClient.saves(id)lists them with their outputs). Without a remote a connector reviews changes on, its step merges the draft athead, the commit the card showed, intomainas one commit titled as the chat and closes the draft, in one git write (Source.merge: a squash in the checkout naming the run in aSanoma-Savetrailer, refused once the draft moved on from that commit, while the checkout has uncommitted changes, or when the two conflict), pushesmaintooriginwhen there is one (a push it refuses is the output’snotPushed; the save stands), and has the worker load the files again and start on them (WorkerOptions.reload, whichsanoma servegives; elsewhere the saved code runs once the instance starts again, which its output’srunningsays). A change to the rules waits foradminhere too: someone outside it is refused (not_approver), since nothing would review it. A save run again after its merge (a worker stopped under it) answers with that commit (Source.saved). With such a remote, Save opens the draft’s change as saved at that head (ChangeInput.save, refused once the draft has moved on): in a round planned at that head, when the policy lets its drafter decide Publish (allowed, or held for a group where nobody else could), the run gives that Publish itself; otherwise Publish waits as asked. - Undo reverts what a save of the person’s chat put on
main(chat, which the step checks:SanomaClient.savedAs): a draft of its own,undo-<sha>(undoDraftOf), with the revert committed on it (Source.revert), saved the same way. - Review starts the built-in
changeworkflow on the draft, as the chat’s person and titled as the chat (SanomaClient.openChange({ id, title, page }, { startedBy }); the run ischange:<id>, andchange:<id>~2for the draft’s next change once that one has ended). Each round pushes the branch and opens its pull request intomain(sanoma.change.open), runssanoma checkon the draft in the box of the person it is by (the app’sAppSteps.check, so a worker without the app’s steps fails it), with its Permissions grid, works out the facts the policy decides the merge on (Policies), asks the policy about the merge ahead, and sets thesanomacommit status on the head, linking the change’s page (sanoma.change.review): pending, or failure while the checks fail or the policy denies. Then it asks one approval, Publish the change, coveringsanoma.change.merge, of whom the policy’s hold names, else of the person who drafted it. A deny waits instead, until something happens to the change. - The review. The app’s Changes section, in the bar when the repository has a remote, lists the changes. A change’s page shows where it is, its branch at the head it last planned, its pull request, the files it edits by kind, the Permissions grid of
mainagainst the branch’s, and Publish. The Inbox shows Publish as any approval, with the change linked. - New commits on the draft start a new round at the new head. The agent tells the change after it commits, which withdraws Publish; a push to the branch on the host, told by its webhook, is read when Publish is decided, which then plans again instead of merging. An approval given in an earlier round lifts no hold on the new head.
- Publish, approved, squash-merges the pull request at the head the round planned, titled
<title> (#<number>), sets the status to success and deletes the branch (sanoma.change.merge); a head that moved meanwhile is planned again, and a merge the host refuses waits. A change to a collection’s columns, opened with its plan (ChangeInput.plan), then brings the records along (A column change; Publish coverssanoma.records.reshapetoo), its counts, or why it failed (the merge stands), the report’s and the state’smerged.reshaped. A hold on the records that Publish does not lift (a pull request merged on the host, with no Publish, or a hold for someone other than Publish’s approver) is such a failure, reported and never waited for: a change waiting there would hold back every deploy ofmain. Try again brings them along afterwards:SanomaClient.reshapeChange(id, { startedBy })starts the built-inreshape(reshape:<id>,~<n>after an ended one; started by nothing else) as the person who asks, over the plan the change carries (refused once the collection’s columns are no longer what the change made them, as after a later change to them, since the plan would then move or delete their values: a renamed or removed field declared again, a rename’s new name gone, a retyped field or a conversion’s new column of another type, a link to another collection, or a conversion’s free-form field no longer free-form; hiding or showing a column changes nothing of it), so the policy decides it as them, a hold waits for its approver in the Inbox, and the ledger records it under them; the change’s view carries its latest one since the merge asretry, with what became of the records once it finished. Then the deploy: the checkout followsmain(a fast-forward, skipped while another branch is checked out, the checkout has uncommitted changes or itsmainhas commits the remote’s lacks; when it moved, the worker loads the files again and starts on them,WorkerOptions.reload), apply runs on the declared hosts the lockfile binds (none before going live, whose apply makes them) as the run<run>:deploy, drift reads them back as<run>:verify, and the draft is closed. The page says Published, with the merge commit and what the deploy did. The change run outlives the deploy’s restart of the worker on the merged code (Versions). - Reject on Publish closes the pull request and the change. A pull request merged on the host deploys as Publish does, and one closed there closes the change: the run checks either on the host before it believes it.
- Who publishes. A change to the rules (a policy, the root’s or an app’s, a people file, or a helper one imports) waits for
adminwhatever the policies say (Policies). A new company’spolicies/changes.cedarholds every other change foradmintoo; replace it with rules on the change’s facts when another group should own part of the repository. - The Permissions line. Under the Permissions grid the app says what the repository’s host enforces on
main(SourceHost.enforcement): a pull request, and thesanomacheck. Where it enforces neither (a private repository on GitHub Free), a push tomainthat does not go through Sanoma is neither reviewed nor decided by the policy.
The app’s actions
Section titled “The app’s actions”What the app does to the company’s repository is a run of a built-in workflow, never a write in the app’s own process, so it works wherever the app is served (a Node process, a Cloudflare Worker) as long as a worker runs: adopt (a drifted field’s value at the vendor written into its data file), patch (a form’s Save; with a column change’s plan and no remote, it also brings the records along, reshaped in its output, and has the worker start again on the new declaration, running, as A column change says), go-live and go-live-host (infra.ts written, then main pushed), go-live-cloud (going live on a host in its vendor’s account, as infra.ts declares it: its address written when it changed, the repository made there, main pushed, then the database and the host applied and waited for), connect-existing, and save-draft (a chat’s draft saved, as Changes says). Their names are sanoma/workflows/shared’s ADOPT_WORKFLOW and the rest. resolveConfig adds them to every config, so a company workflow may not take their names, and describeConfig lists them with builtin: true. Each takes a zod input (AdoptInput, PatchInput, GoLiveInput, GoLiveHostInput, GoLiveCloudInput, ConnectExistingInput, SaveDraftInput), refused at the start, and its run is a step: the app’s page starts it and polls its .result.
What each does is the app’s, given to the worker as AppSteps (startWorker(config, { app, source }); sanoma serve and sanoma worker give theirs, sanoma/app/steps). The run calls its step in a DBOS step of its own (app:<name>) with an AppStepContext: the worker’s own SanomaClient (connected on first use, closed when the worker stops), its source, its reload when it was given one, and serially, the worker’s one lock on it, which a step holds around reading, writing and committing the checkout, the config and its resolution, who started the run (by) and the run’s id. A step refuses by throwing: a SanomaError whose code and data the page reads (invalid_input with its issues or a field, not_approver), else an error whose message the run fails with. A step that applies after its write answers what to apply ({ apply }), which the run starts as its child, <run>:apply, as its own actor, and answers that run’s id without waiting for it: an apply may wait for its plan’s approval in the Inbox. go-live-cloud is the one that waits (AppRunner.applyAndWait), failing when the apply left a step undone, and the one that calls an operation: the host type’s account.repository, through ctx, so the policy decides it and the ledger records it. On a worker without app steps each run fails, saying so. The pages call them through api, typed as AppApi.
Changes
Section titled “Changes”- 0.11.25: the
workload-identityauthentication kind is removed, with theWorkloadAuthenticationandAuthenticationContexttypes; no connector used it. Every method now keeps a bundle in the store:defineConnectionrequirescredentials, andverifyAuthentication(method, credentials)takes no third argument. A federated identity stores its bootstrap secret as anapi-keybundle, as GCP provisioning does. - 0.11.0: the config’s
logintakesfrom, the address sign-in codes are sent from, and requires it: a config withloginand nofrom(or one that is no email address, or a sender that does not keep it) is refused when it loads, so the worker, the app andsanoma checkdo not start until it is set (Signing in on a host). It replaces the Resend connector’s retiredRESEND_FROM.
License: FSL-1.1-ALv2.
The server-only GCP KMS credential store is a managed-backend option with explicit company-scoped bootstrap. It requires reviewed IAM/database isolation and does not provision Cloud infrastructure.
These pages describe sanoma 0.11.24.