Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Current configuration and source-status guidance — 10 November 2026
Source-qualified from DEP-13 part 1 and SCRUM-4977/spec 532 part A, merged from upstream at bd60c9c8dd; this addendum describes source contracts, not a new runtime or deployment proof. The pinned historical body below remains unchanged. Its ticket-status table and planned-phase text are historical; use this dated addendum for the current implementation boundary.
Current implementation boundary
The current application source contains deployment administration (scoped grants, environment definitions, peer trust and pairing, peer grants, outbound allowances, signing keys and trusted signers), signed-release preparation (candidate selection, build, view, configuration check, download and inspection), target mapping, and a request to create a workspace on a paired push target. The current workspace creation operation prepares the target workspace; it does not copy a release into it.
The current application source does not contain a complete release-deploy or rollback controller workflow, nor a supported customer-facing CLI that performs a whole release rollout. The existing workspace-import endpoint accepts a signed release input but still applies its import admission checks; a governed-only whole-app release may be refused by this direct-import route. Keep package creation, inspection, import result and target application acceptance as separate states.
The server-wide inflow.deployment.release-enabled value defaults to off and is restart-activated. Normal application startup loads it through the canonical feature-configuration store, which accepts only trimmed, case-insensitive true or false; an invalid value is rejected during startup configuration. The lower-level DeploymentReleaseFlag.fromSetting helper treats values other than true as off, but that fallback does not override canonical startup validation. In the current source, target workspace creation requires this gate and returns DEPLOYMENT_RELEASE_DISABLED when it is off. Enabling the flag does not create deploy/rollback functionality or waive authorization, trust, target admission or import rules. Do not treat this reference as an instruction to change a live server's configuration.
Read the historical status section below carefully
The ticket-status table and release-flag narrative retained later in this reference are a historical snapshot from its source baseline, not a current route inventory. In particular, do not use its “Deploy, rollback — Not yet delivered (DEP-06a onward)” row or its later list of routes supposedly enabled by the release flag to infer the current implementation. On the current source described above, the flag gates target-workspace creation; a complete release-deploy and rollback workflow and a customer-facing full-rollout CLI are not present. The current contract, not the old ticket status, determines what an administrator may automate.
Current source references: FeatureFlagCatalog.java, FeatureConfigurationStore.java, CanonicalFeatureEnvironmentPostProcessor.java, DeploymentReleaseFlag.java, DeploymentTargetMappingController.java.
Deployment configuration (DEP-13 part 1)
Configuration holds the values this workspace needs on each destination server: settings, connected system addresses, contract aliases, feature switches, secret references, person/group/role mappings and document locations. The values do not travel with a release; each server gets its own.
- Where: open the workspace, then Deploy → Configuration. Each row is an item; each column is a destination environment you may view.
- Who may see it: a person with a deployment View grant on at least one active environment and at least the Viewer role in the workspace. Only the environments you may view become columns. Without any, the section is not shown and Studio makes no request for it.
- Who may change it:
- Items (add, edit description and required, remove): the Admin role in the workspace plus a deployment View grant on at least one active environment.
- A value: the Admin role plus a deployment View grant on that environment. The environment is authorized before it is looked up, so an unknown, retired or hidden environment is refused the same way.
- Removing an item clears its values on every server, so it needs the right to change values on every active environment where it has one.
- API keys neither read nor change configuration.
- Kinds and their values (checked on the server; a refusal names a fixed reason, never the value):
- Setting (
VARIABLE): text (up to 4,000 characters), a number (for example60or-12.5) or yes/no. - Connected system address (
CONNECTOR_ENDPOINT): an absolutehttps://URL (http://only for the loopback hostslocalhost,127.0.0.1or::1), without user name, password or#part, up to 2,000 characters. - Contract alias (
ALIAS_BINDING): the contract the alias binds to on that server, picked as<owner workspace key>/<contract key>(SCRUM-5022). A bare alias key stored before part B stays as it is. - Feature switch (
FEATURE_SWITCH): on or off. - Secret reference (
SECRET_REF): a credential in the destination server's vault, picked, never typed (SCRUM-4551). For a connected system's credential (connector.<system>.credential), Set value lists, by name, the credentials of the mapped target workspace that the destination lets this server bind for connected systems. The value saved is that credential's vault reference (vault:<id>), checked again on the destination before it is saved. The cell never shows the reference or any secret: it shows the credential's name and whether it Resolves on that server now (with its last rotation), or Revoked, Not allowed, Not found, No target, Not paired or Not checked (the server could not be asked). The grid asks each server when it opens; Check secret references again asks again, for example after a rotation or revocation there. Nothing is cached. A secret item whose key names no connected system cannot be set. A value saved earlier in thevault:<scope>/<name>form shows Not found; pick the credential again. - Who may bind a credential (destination side). A credential resolves for a paired server only if it belongs to exactly the mapped target workspace (never a platform credential, never another workspace's), is not revoked, and its binding policy names the deployment service account of that server's workspace grant and allows the purpose (
CONNECTED_SYSTEM). With no policy, nobody may bind it. A deployment administrator can review and replace the policy through the destination Credentials page; the binding-policy API remains available to supported administrative clients. Every change is audited with the old and new policy (DEPLOYMENT_CREDENTIAL_POLICY_CHANGED). The page can rotate or revoke credentials it created; credentials owned by another feature remain managed by that feature. - Credentials page (destination side, SCRUM-4552). Authorization → Deployment → Credentials, for deployment administrators. Pick a workspace (nothing is pre-selected) to see its vault credentials: name, whether it was created here or by another feature (for example a connected system), active or revoked, created and last rotated, and who may bind it. No value or vault reference is ever shown.
- New credential stores a credential for that workspace: a name and one to ten secret fields (for example
apiKey), entered in password fields. The workspace is the credential's scope for its whole life. Values go into the vault once and are never shown again; the vault audits the store. - Rotate (credentials created here) replaces the secret fields; the name, scope and who may bind it stay. Revoke (created here) needs the credential's name typed; afterwards no server can use it and it cannot be restored. Credentials of other features are rotated and revoked from those features.
- Who may bind (any active credential) picks the deployment accounts and purposes from what this server has; nothing is typed. With none chosen, nobody can bind it.
- New credential stores a credential for that workspace: a name and one to ten secret fields (for example
- Person, group or role (
PRINCIPAL_BINDING): the item key is the portable reference a release names (ref:user:<name>,ref:group:<key>orref:role:<id>); the value is that server's own user name, group key or role id. - Document location (
DOCUMENT_LOCATION): a cabinet or folder of that server, picked as<cabinet id>or<cabinet id>/<folder id>and shown by its readable path (SCRUM-5022). A path typed before part B, such ascontracts/crew-ops/2026, stays as it is.
- Setting (
- No secrets in cells: every value and description passes the secret scanner; a value that looks like a password, token or key is refused, so secrets can only be referenced.
- Item keys: for every kind except Person, group or role (
PRINCIPAL_BINDING), use lower-case letters and digits joined by single.,-or_, starting with a letter (2 to 120 characters). Contract-alias and document-location items, which a release adds from its needs, may also use the source's own key (SCRUM-5022): an alias may start with a digit or repeat a separator; a document rule's key may use upper case, inner spaces and a single character. Principal-binding items instead use the portableref:user:,ref:group:orref:role:reference grammar described above. Keys are unique in the workspace. Key, kind and value type never change; remove and add again instead. - Pick release-backed items (spec 532): in Add a configuration item, choose Something a release needs for a destination-backed artifact. The picker lists keys required by built releases of this workspace that are not defined yet and names the releases that need each key. This covers principal references, connector items (including
connector.*settings), secrets, aliases and document locations. A setting or feature switch that belongs only to this workspace uses A setting of this workspace. The server refuses arbitrary or no-longer-needed artifact keys (DEPLOYMENT_CONFIG_NOT_NEEDED); a key needed with conflicting kinds, or an unreadable release's needs, cannot be added from the picker. - Pick current target principals (spec 532): for
ref:user:andref:group:values, the choices come from the selected environment's paired server. People are active human members of the mapped target workspace; groups are the receiving server's active groups. The picker offers at most 25 choices per response, and save asks the target to confirm the exact selected key again. If the paired target changed or no longer offers the choice, the save is refused. Roles, contract aliases and document locations are picked the same way (next item). - Roles, contract aliases and document locations (SCRUM-5022): these values are picked the same way, from the mapped target workspace on the paired server, with nothing pre-selected and nothing typed. A role (
ref:role:) is one of that server's roles, by role id. A contract alias is one of the published contracts that workspace can use, stored as<owner workspace key>/<contract key>because contract keys are unique only within a workspace. A document location is one of that workspace's own cabinets or folders, stored as<cabinet id>or<cabinet id>/<folder id>and shown by its readable path; a folder is never matched by name. The picker names the workspace on that server it lists from. The server asks the other server for exactly the picked key again before saving. A release needs a document location for each document rule that writes into a fixed folder, and an alias binding for each contract alias it carries, so these items are added from the release like any other need. - Missing values: a required item without a value on a server shows Missing there. Which items a given release needs is decided by DEP-13 part 2.
- Add from the release (spec 532): in Configuration it needs, Add to this workspace creates that row's required key, kind and flag, without a value. The action above the rows says Add the missing item for one item or Add all N missing items for several (N is the displayed count). Existing items stay unchanged; a conflicting-kind key is omitted from the bulk action. A refused add withdraws the controls while Studio checks access again. After a successful add, the release can still report Missing until an authorized administrator saves the environment-specific value. Adding items and values does not apply configuration on the destination server; application deployment remains a separate operation.
- Concurrent edits: every change names the item and the revision it was based on. A change based on an older read is refused (
DEPLOYMENT_CONFIG_STALE, 409); the dialog then shows the current value. A cleared value keeps its revision, and a re-created item is a new item, so a change read before either is refused. - History and audit: every change appends a history row (who, when, server, old and new value), which cannot be updated or deleted, and writes
DEPLOYMENT_CONFIG_CHANGED(for a value change, the item, environment and revision but nothing derived from the value, since the audit log is readable without the environment's deployment grant; the old and new values are in the history). History on each row lists changes newest first, showing value changes only for the environments you may view. Removing an item keeps its history. - Storage:
deployment_config_items,deployment_config_valuesanddeployment_config_history(migration000427). - API:
GET /api/workspaces/{workspaceKey}/deployment/config;POST …/config/items{key, kind, valueType, required, description};PUT …/config/items/{itemKey}{itemId, expectedRevision, required, description};DELETE …/config/items/{itemKey}?itemId=&expectedRevision=;PUT …/config/items/{itemKey}/values/{environmentKey}{itemId, expectedRevision, value}(0 for a value never set);DELETE …/values/{environmentKey}?itemId=&expectedRevision=;GET …/config/items/{itemKey}/history. The capabilitiesdeployment.config.viewanddeployment.config.manageare workspace-scoped.
Setting a value changes nothing on the destination server. Applying configuration during a deployment arrives with DEP-17.
Current release identity conflicts — SCRUM-4978 (source reviewed 9 November 2026)
This note is a source-qualified description of the release ledger and native import review on current master 4efe209342; it does not claim that an import or target journey was executed. The pinned technical body below is restored exactly from the preceding documentation candidate.
The import ledger identifies a source by the server this receiver trusts and that source workspace's key. It does not use a matching display name or key as proof of ownership. A same-key business function or contract binding that has no recorded owner blocks import even if the target's content looks identical; an item owned by a different trusted source also blocks it. A rule or process that names a business function absent from the release follows the same ownership check. The platform's default general business function is the exception.
The Review lists identity conflicts. For a conflict the native Studio review considers adoptable, and when the signed-in administrator has the required management authority, Studio offers Adopt… with a typed-key confirmation. The adoption service separately checks target authority, the exact typed key, an adoptable family and a source this server trusts; it records the source relationship and DEPLOYMENT_LEDGER_CHANGED but does not import the release. The native import review checks its release again afterward, and Import remains unavailable while another blocking conflict remains. A governed-only route remains unsupported; adopting an item does not make that route importable.
Adoption does not replace a business function: the function stays as it is and release assets can be placed in it. A contract binding keeps its current contract until import, when the operator selects the target contract. Existing rule or contract versions remain, and the source release may publish its version on top. When the release expects different business-function details, the native Studio review does not offer adoption; the function owner must align it and the release must be reviewed again. Another source's ownership is not taken over. The ledger retains ownership when a function is deleted, so deletion does not free its key for another source.
Paired-server trust identifies a source across signing-key rotation; a key trusted from a file is itself a source, so a replacement key is a different source. Creation, adoption and import are rechecked within the transaction under the workspace writer fence. When a process-bearing release has no principal directory to perform the required literal check, the receiver refuses it instead of skipping that check.
Sources: SCRUM-4978 readiness entry, WorkspaceImportDialog.tsx, ReleaseLedger.java, and ReleaseWorkspaceImport.java.
Package contents policy (SCRUM-4553, DEP-15)
Each workspace has one package contents policy, shown on Authorization → Deployment → Releases under Package contents once a workspace is chosen. It decides what whole-workspace releases of that workspace carry. A release of selected assets always carries exactly what is chosen, plus what those assets need. If there is no saved policy, whole-workspace releases start with the whole workspace and reference data included, with no exclusions.
- New releases start with: the scope Build a release opens on (the whole workspace, or selected assets, which opens the asset picker at once).
- Reference data: whether the reference datasets marked to travel on the Reference data page go into whole-workspace releases.
- Left out: up to 200 published assets (family and key, any version), picked from the workspace's published assets. Nothing is typed.
Rules the server enforces:
- Reading needs a deployment VIEW or BUILD grant for the workspace (signed-in person, no API key). Changing it needs BUILD. Studio shows Edit package contents only to people who may change it.
- An administrator only sees, and can only remove, the exclusions they can read. Exclusions they cannot read are kept when they save, even while the asset is not published. Build a release becomes available once the policy has been read.
- Each save carries the revision it was read at. A concurrent change is refused (
DEPLOYMENT_PACKAGE_POLICY_STALE, 409), and the dialog then shows the current policy. An unknown, unreadable or duplicated asset, or more than 200, is refused (DEPLOYMENT_PACKAGE_POLICY_INVALID, 422,field). Every change is audited once asDEPLOYMENT_PACKAGE_POLICY_CHANGED, with the old and new scope, reference-data switch and exclusion lists. An unchanged save writes nothing. - A whole-workspace build applies the policy it reads in its own transaction. The builder must be able to read every asset of the workspace and everything those assets depend on, left-out ones included, so a policy never lets someone release a workspace they could not release without it.
- A left-out asset that an included asset needs still travels, at the exact version needed, and does not change what is active on the receiving server. The release shows it as Needed by …. What only a left-out asset needs stays out too, but is still authorized. What stays out is listed in the signed notes (
leftOut) and under Left out by the package policy when the release is opened. Because the file names those assets, listing, opening and downloading the release need read access to them too, as for its entries. The build's audit row records the policy revision it applied. - A release built while no assets are left out has no
leftOutfield, so its manifest bytes and signature are as before. A receiving server older than this change refuses a manifest that does carryleftOut, because manifests are read strictly. Upgrade the receiver first.
API: GET/PUT /api/deployment/releases/package-policy?workspaceId=<id>. The PUT body is {defaultScope: WHOLE|SELECTED, includeReferenceData, exclusions: [{family, key}], expectedRevision}, and the response is {defaultScope, includeReferenceData, exclusions: [{family, key, name}], revision, updatedBy, updatedAt, canEdit}. The policy is stored in migration 000440 (deployment_package_policy).
Compare a release with an environment, or dry-run it (SCRUM-4554, DEP-16)
In an opened release, Compare with an environment appears when at least one mapped environment has a live trusted link and the signed-in person has deployment Deploy authority there. The environment picker is limited to those options. Before sending the release file, the source server also requires its distribution grant to allow that release over that link. If that consent is missing, the request is refused and nothing is sent or stored.
Compare asks the receiving server how the signed release relates to the mapped workspace there. The target requires an active Workspace peer grant that includes Compare and a usable deployment account. The target reviews the release as that account, so its own current access controls which details it can read. No asset is installed or changed.
The report includes each source release entry's family, key, release version and activation flag, as well as its target-facing status and any permitted target-side version or diff. If the target deployment account cannot read an asset, the report withholds target-side details and uses a status such as Not readable there; it does not hide the source release's family/key or release metadata from a person who can read that release. Changed assets can show a before/after field diff, capped at 50 changed paths per asset; at most 200 assets receive a field diff. The receiving server can also report compatibility, ledger, data-model, configuration, secret-reference and running-case findings.
Dry run performs the comparison and also runs each asset family's validation for every release entry inside a transaction that is rolled back. The target remains unchanged. This checks asset validations; it does not rehearse the deployment runner or guarantee that a later deployment will succeed.
The result is stored with the release in deployment_comparison (migration 000442) and audited as DEPLOYMENT_COMPARISON_RUN. The audit stores identifiers, environment, kind, outcome/refusal code and the count of blocking findings; it does not store field values from the report. The report is bounded and excludes secret values. A person needs View on the environment and permission to open the release to read a saved comparison. Earlier comparisons lists the readable results, newest first. A refused or unreachable target is shown with a plain-language status; it is not treated as a successful comparison.
| Example result | What it tells the operator |
|---|---|
| A rule is Changed and shows a before/after diff | The release contains a different value for that rule. Review the changed paths and target context before deployment. |
| A required setting is missing for the environment | The comparison has found a deployment blocker. Set an approved value through the workspace's Configuration page, then compare again. |
| A running case stays on its current version | The case is reported as a notice; it is not silently migrated by Compare. |
| The target reports a ledger conflict | Resolve the ownership conflict through its authorized native workflow; comparison does not adopt or import the asset. |
The API is GET /api/deployment/comparisons/options?workspaceId=, POST /api/deployment/comparisons?workspaceId= with {releaseId, environment, kind: COMPARE|DRY_RUN}, GET /api/deployment/comparisons?workspaceId=&releaseId=, and GET /api/deployment/comparisons/{id}?workspaceId=. Structured refusals include an invalid request, an unmapped workspace, an unreadable result and an oversized report. The signed target peer route is /api/deployment/peer/target/compare; the receiving server accepts a bounded release request, and the source reads at most a 4 MiB peer response within 120 seconds. Release content itself is limited to 64 MiB before packaging overhead.
Sources: comparison API, source-side checks and saved results, target-side comparison, asset review and findings, release comparison panel, and comparison storage. The references describe source behavior; this manual update did not execute a comparison against a live deployment.
Migration plans for contract changes (SCRUM-4555, DEP-16a)
A comparison lists every change that would break existing data on the receiving server (a field becomes required, a field or record type is removed or renamed, a type or length narrows, enumeration values are removed). Each one blocks a deployment until a migration plan covers it.
- Plan the migration appears in a completed comparison that reports such changes, for people with the deployment DEPLOY grant on that environment. It opens the plan editor for the subjects the comparison named: one plan per data model (its record types and fields) and one per enumeration field (its removed values), from the version the receiving server has to the version in the release (each server numbers its own versions, so plans are anchored to what that server reported).
- Each change offers only the actions the server allows for it: Set a default value (with Backfill existing records), Convert, with a value for what does not fit, Drop the data (the explicit acknowledgement), Keep the values (for a rename) and Map each removed value (to values of the field in the release). Some changes cannot be covered by any rule (a new uniqueness rule, a changed key, a removed relationship); they stay blocking.
- Save revision writes a new revision. A revision never changes afterwards: its rules and its SHA-256 fingerprint are fixed (the database refuses any edit). The server validates it against the comparison it was written from and the field types in the release, and answers per change in words.
- Approve revision N needs the deployment APPROVE grant on the environment and a revision that covers every change now.
Approving supersedes the earlier approved revision. Writing needs DEPLOY; reading needs VIEW (otherwise the neutral
not-found). Both are audited (
DEPLOYMENT_MIGRATION_PLAN_REVISED,DEPLOYMENT_MIGRATION_PLAN_APPROVED; ids and hash only). - Every later Compare and Dry run sends the approved revisions for that environment with the release. The receiving server checks each one again (its fingerprint must match its content, and its rules must cover that server's own changes); a covered change becomes the notice an approved migration plan covers this change (revision N). The stored report lists the bound revisions and fingerprints, which the deployment intent (DEP-17) binds.
- In the comparison, the data model's row says Blocks deployment while any of its breaking changes has no approved plan, and Covered by a migration plan once every one has (decided by the server). Its Data models section names record types and fields by their display names from the release. Plans show the people who wrote and approved them by display name; the stored revision keeps their identity.
- Values are checked as the receiving server stores them: text lengths, decimal precision, microsecond times and RFC 3339
timestamps, enumeration values within the release's domain and 64 characters, JSON (not
null), Base64 for binary, and a JSON list whose elements fit the list's element type. Native (database-specific) fields and lists of references take no rule value. - A plan is visible only to someone who may open every release it was written for. Compare and Dry run bind only such plans for the person comparing, saving never extends a plan they cannot see, and a saved comparison that bound a plan they cannot read is not listed or opened.
- Authorization → Deployment → Migration plans lists the plans of a workspace for an environment, with each revision's state, who saved and approved it, its fingerprint and whether it covers the changes now.
Storage: deployment_migration_plan and deployment_migration_plan_revision (migration 000443). API (source):
GET /api/deployment/migration-plans/candidates?workspaceId=&releaseId=&environment=,
GET /api/deployment/migration-plans?workspaceId=&environment=, GET /api/deployment/migration-plans/{id}?workspaceId=,
POST /api/deployment/migration-plans/revisions?workspaceId= {releaseId, environment, family DATA_MODEL|ENUMERATION, subjectKey, rules[{recordType, field, kind, action, value, backfill, valueMap}]},
POST /api/deployment/migration-plans/{id}/revisions/{revision}/approve?workspaceId=. Codes:
DEPLOYMENT_MIGRATION_PLAN_INVALID (422, field), _NOT_VALID (422), _NO_COMPARISON (422), _STALE (409),
_NOT_FOUND (404).
Governed admission and Production confirmation (SCRUM-4556, DEP-17a part 1)
A receiving server decides for itself which of its workspaces are managed deployment targets and which of those are Production. A workspace is managed when an active peer grant targets it, its target class is declared (Authorization → Deployment → Peer access), or it is in the Production tier. A managed workspace is Production when its class is declared Production, when its class is undeclared, or when it is in the Production tier. An unmanaged workspace with no declared class is not thereby Production. Nothing a source server registers changes this; registering a Production workspace as "Test" on the source changes nothing here.
- A managed workspace refuses legacy packages (formats 2 and 3) and every import that does not come through admission
(
WORKSPACE_IMPORT_MANAGED_TARGET, audited asWORKSPACE_IMPORT_REFUSED). A plain workspace with none of the above keeps importing every format as before. - Importing a signed release (format 4) or adopting an asset for a release's source goes through one admission: the
deployment release flag must be on (
DEPLOYMENT_RELEASE_DISABLEDotherwise); the caller must have Admin access on the workspace; and on a Production workspace a typed Production confirmation made for exactly this change is required (DEPLOYMENT_PRODUCTION_CONFIRMATION_NEEDED). Inspecting a release for a managed workspace is allowed (it changes nothing). - A Production confirmation is made in Studio by typing the workspace's name. It is stored, bound to the workspace, the
operation (import or adopt), the release hash or adopted asset, and confirming administrator; it is valid once for 15 minutes and consumed in the same
transaction as the change. Only a person in an interactive browser session makes one: API keys, scoped tokens, MCP and
agents never can (
DEPLOYMENT_NOT_AUTHENTICATED). Making one and using one are audited (DEPLOYMENT_PRODUCTION_CONFIRMED,DEPLOYMENT_ADMITTED; identifiers only). Stored in migration000444. - Later parts of DEP-17a add approvals bound to the intent and admission for the peer, offline, deploy, rollback and resume entry points.
API: GET /api/deployment/admission/requirement?workspaceId= (workspace administrators: {managed, productionConfirmation, confirmName}), POST /api/deployment/production-confirmations with {workspaceId, operation: IMPORT|ADOPT, subject, typed}
returning {id, expiresAt}; POST /api/workspaces/import and POST /api/deployment/ledger/adopt take productionConfirmation.
The frozen deployment intent (SCRUM-4556, DEP-17a part 5)
A change to a managed workspace does exactly what the person reviewed, or nothing. Pressing Import (or Adopt) in Studio first freezes a deployment intent on this server; the Production confirmation is then made for that intent, and the import or adoption names it.
- What is frozen. The review's
targetFingerprint(a SHA-256 of what the review said about this workspace, as this person saw it; the freeze recomputes it and refusesDEPLOYMENT_INTENT_CHANGEDwhen it differs), the workspace state behind the review without per-viewer redaction (only its hash, never returned), whether the workspace is managed and Production, the active peer grants naming it (id and revision), the release's signer (key id, status, revision), and for each dependency the chosen contract as it is now (owner, key, kind, target, visibility, status, whether this workspace may call it) and the alias's current binding. An adoption freezes the asset itself (a rule's versions and draft, the contract, the business function or the binding), its ledger owner and the source's signers. - The intent is valid for 60 minutes, for one change, by the person who froze it, with the same operation, release or
asset and bindings. Its identifier is a SHA-256 over the frozen facts and a random value kept nowhere, so it reveals
nothing about them. Stored in migration
000454(deployment_intent); auditedDEPLOYMENT_INTENT_FROZEN. - Under the hold the server checks everything again in the change's own transaction: the release flag, the intent
(still pending and unexpired, read with a fresh clock), and every frozen fact. The signer's row, the source's signers,
the chosen contracts and any grant a contract depends on are locked until the change commits; peer grants naming a held
workspace and its class cannot change while it is held (
DEPLOYMENT_WORKSPACE_HELD). A difference refuses the change withDEPLOYMENT_INTENT_CHANGED(409,changed: the names of the facts) and invalidates the intent and its confirmation; the invalidation is recorded (DEPLOYMENT_INTENT_INVALIDATED) even though the change is refused. An intent that has expired is refused withDEPLOYMENT_INTENT_EXPIRED(409); a change without a usable intent withDEPLOYMENT_INTENT_NEEDED(422). - Tightening applies, loosening does not. A workspace that became managed or Production after the freeze is a change (refused, review again). A workspace that stopped being Production still needs the confirmation the intent was frozen with. An intent named for a workspace that is no longer managed is still checked, so revoking its grant never lets an old intent through.
- Production confirmation. Made for the intent's identifier (
subject), only while the intent is pending and only by the person who froze it. A confirmation made for a release hash (before this part) is never accepted. - Studio says "This workspace changed after you reviewed the release. Review it again, then import." (or that the review is more than an hour old) with one action, Review again, which checks the release again and keeps the file and the bindings.
- Not in this part: the source-side facts of a governed deployment (comparison, source configuration and mapping revisions, stage policy, migration plans), approvals bound to the intent, rollback eligibility and blocked releases. They belong to the intent a source creates and dispatches (DEP-17b, T157c).
API: POST /api/deployment/intents with {operation: "IMPORT", release, bindings, reviewedFingerprint} or
{operation: "ADOPT", sourceServer, sourceWorkspace, family, key} in the workspace context, returning {managed, intent, expiresAt, productionConfirmation, confirmName} (an unmanaged workspace: managed: false and no intent);
POST /api/workspaces/import and POST /api/deployment/ledger/adopt take intent; the release review
(POST /api/deployment/releases/inspect) returns targetFingerprint.
Deployment runs (SCRUM-4559, DEP-17 part 1)
A signed release imported into a managed workspace through the deployment ledger (business functions, rules, contracts and contract bindings) runs as a deployment run: ordered steps the server applies one by one, each saved with its result, so a failure or a server stop never repeats or loses a step. Other families still import in one transaction until later parts of DEP-17; an unmanaged workspace imports exactly as before.
- Starting.
POST /api/workspaces/importanswers 202{run: {id, status}}instead of the import report. The admission (intent, confirmation, hold) creates the run QUEUED with its steps in one transaction and keeps the workspace hold for it; the run executes on the server (migration000455). - Steps. Business functions, rule mappings and rule versions in pin order, contracts, contract bindings, then a check that everything arrived as reviewed. Each step has a durable operation id (intent hash, family, source key, source version, step kind) and commits its effect and its checkpoint in one transaction.
- Workers. The database is the run queue (polled every 5 s). A worker holds a fenced lease (token, owner, 60 s expiry, renewed per step); a stale worker cannot commit. On every acquire the worker rotates the hold's admission token, so the database guard admits its writes and no earlier worker's. Each step runs as the requester (identity, workspace and credential ceiling restored) inside the admission context.
- Checks. Before the first change the frozen intent is checked again (a change cancels the run, ends the intent and releases the hold). Before every step: the release flag, the run's hold, the release not blocked, the target's policy and grants equal to the frozen ones, the signer (row-locked), and the requester's authority. A failure stops the run.
- Busy items. A step whose item is being changed elsewhere (its lock is not available in time) stops the run with
DEPLOYMENT_RUN_ASSET_BUSYnaming the item; Studio says so and shows the step as Stopped; Resume once that change is done. While stopped so, the run view says whether the item is free now (itemFree; for a rule, a non-blocking try of its native lock, released at once); Studio re-checks every 3 s (bounded) and says when it is free again. - Partial. A failed step leaves the run FAILED_PARTIAL: applied steps stay, the workspace stays held (S12).
POST /api/deployment/runs/{id}/resume(workspace administrators) checks the same and that the workspace equals its frozen baseline plus the run's own applied steps; any other change refuses withDEPLOYMENT_RUN_DRIFTnaming the asset. A worker that takes over a stopped run makes the same drift check before any further step. - Abandon.
POST /api/deployment/runs/{id}/abandonwith the typed workspace name (deployment administrators), or Abandon hold on Peer access: the reconciliation (each step applied, applied and changed here, or not applied) is stored, the run becomes ABANDONED and the hold is released in one transaction. Nothing is rolled back in this part. - Reading.
GET /api/deployment/runs/{id}(and?intent=for the requester) and the server-sentGET /api/deployment/runs/{id}/events, for people who administer the workspace under their current credential: status, steps (family, key, name, state, outcome) and the report; never the release file or internal facts. The stream re-authorizes before every event and every 30 s. Studio follows a run by polling its state. - Blocked releases.
GET/POST /api/deployment/blocked-releases,DELETE /api/deployment/blocked-releases/{hash}(deployment administrators, auditedDEPLOYMENT_RELEASE_BLOCK_CHANGED): a blocked hash is neither frozen nor admitted, and a run stops at its next step. - Audit.
DEPLOYMENT_RUN_CHANGED: created, step applied, failed, resumed, continued, cancelled, succeeded, abandoned (ids, step numbers and keys, outcome codes; never content).
Removals in a deployment run (SCRUM-4559 part 2, SCRUM-4556 T157d)
A release's tombstones (what the source removed since its baseline) are applied by the run of a managed ledger import,
after every publication and binding and before the final check: contracts are revoked (REVOKE_CONTRACT), then rules
retired (RETIRE_RULE), then business functions deleted (DELETE_FUNCTION), each through the family's own secured,
audited service, with a key-level removal record in deployment_ledger_removal (migration 000456) in the same transaction.
- Ownership. Only a key the ledger says this release's signer owns here is removed. A key that is here but owned by
nobody or by another source refuses the import (
DEPLOYMENT_REMOVAL_NOT_OWNED); one that is not here, or is already removed, is reported as already absent and gets no step. - Families. A tombstone of any other family (including contract bindings, whose uses are not indexed) refuses a
managed import (
DEPLOYMENT_REMOVAL_UNSUPPORTED): the release is never reported imported while something it removes stays. Unmanaged imports keep applying no tombstones. - Platform removal rules. A removal the platform would refuse natively is refused, at admission (nothing applied) and
again in its step (the run stops, the hold stays, Resume re-checks):
DEPLOYMENT_REMOVAL_REFERENCEDwithwhere:here(a consumer in this workspace: the impact service's removal check, live cases included; a contract here that targets the rule; a function's assets or Home settings),elsewhere(a binding in another workspace, never named or counted),release(the release itself still uses it, or binds an alias to it),receipt(a rule's live-test receipt to reconcile),configuration(Home settings keep the function once chosen) orunverified(the platform cannot currently prove the rule's dependency coverage; today this refuses rule removals in realistic workspaces, SCRUM-5124). The person also needs the native authority to remove the item (credential ceiling and object access). - Re-introduction. A later release that carries a removed key is refused (
DEPLOYMENT_REMOVAL_REINTRODUCED) in this part. - Removal fence (T157d). While an open run (QUEUED, RUNNING, FAILED_PARTIAL) has a removal step to apply, a new
binding to that contract from any workspace is refused (
DEPLOYMENT_REMOVAL_CANDIDATE, 409). The binding share-locks the contract until it commits and the revocation locks it for update, so one always sees the other. New references inside the held workspace are refused by the write fence. A case started on a version that depends on a retiring rule makes the rule's removal check refuse (every consumer except history-only blocks), so the run stops instead of stranding the case. - Downgrade.
000456down refuses while removal steps or records exist.
Workspace settings in a deployment run (SCRUM-4559 part 3)
A release's workspace-settings entry (spec 516: AI policy, publishing governance, deletion policy) is applied by the run of
a managed import as one APPLY_SETTINGS step (migration 000457), after the publications and bindings and before the
removals. The step's baseline is the workspace's effective settings at admission, its expectation the release's.
- Effect. Under the deletion-policy lease (the workspace row lock), the step compares the effective settings with the
baseline (different:
DEPLOYMENT_RUN_DRIFT, familyworkspace-settings, nothing written), writes each policy that differs through its secured, audited service (WORKSPACE_AI_POLICY_UPDATED,WORKSPACE_PUBLISHING_GOVERNANCE_UPDATED,WORKSPACE_DELETION_POLICY_UPDATED, old and new values, by the requester), reads the result back and checkpoints, all in one transaction. Matching settings keep their step (the expectation for drift and VERIFY) and write nothing. The hold trigger (000453) refuses every other settings writer from admission until the hold is released; a writer already in progress holds the admission off until it commits. - Routing. A release with settings is importable only by a run into a managed workspace (
settingsChangeCHANGES or MATCHES in the review). On an unmanaged workspace it is governed-only (UNMANAGED); the one-transaction import refuses it. A person the native settings services would not let read this workspace's settings (a member, orWORKSPACE_VIEW) getsNOT_REVIEWABLEand is refused at admission (DEPLOYMENT_SETTINGS_NOT_REVIEWABLE, 403), so nobody imports changes they were not shown. The settings here are part of the frozen intent. - Authorization.
WORKSPACE_MANAGEandWORKSPACE_VIEWwithin the credential ceiling at review, admission, every step and Resume; ADMIN membership through the native services. Resume is offered only when the resumer's credential covers the run and its original requester still administers the workspace. - Canonical lists. Allowed models and providers must be sorted, unique, unchanged by
trim(), not blank, without commas or control characters, and not local ids (recomputed on receipt), so an applied list reads back as frozen. - Ownership. None: settings belong to the workspace; any trusted source's later release may change them again. The
run's report (
settingsChanged, from the step's frozen values) records what changed; readers who may not read the settings see the setting names only. - Downgrade.
000457down refuses while settings steps exist.
Business calendars in a deployment run (SCRUM-4559 part 4)
A managed run applies each business-calendar entry as an APPLY_CALENDAR step (migration 000458), before every other step.
- Ownership first (owner key: the name lower-cased). Another source's owner is a conflict (
OWNED_BY_OTHER_SOURCE) whether or not a calendar exists; this source's owner updates the calendar (or creates it again after a native deletion, keeping the owner); no owner creates an absent calendar (owner recorded with the effect) or is a conflictNOT_OWNEDfor one made here (adoptable:PROCESS_CALENDAR_MANAGE, typed confirmation, full calendar snapshot in the frozen facts). This workspace's default calendar is a conflictDEFAULT_CALENDAR(not adoptable) and is never written. - Faithful write.
BusinessCalendarService.applyDeployed(PROCESS_CALENDAR_MANAGE and an effective EDITOR role) writes throughreplaceDeployed: create with the id chosen at admission, or replace name, zone, week and every date row at the frozen revision, each date with its review state, origin and import fields; auditedBUSINESS_CALENDAR_CREATED/UPDATEDwith{deployment: true}. The step reads the calendar and owner back (id, content, not default, owner) before its checkpoint. - Preflight (before anything is held): storage-canonical content (NFC name; dates in export order; imported dates with
a two-letter country, a year 1900-2200 and a trimmed key; other dates confirmed without import fields; no control
characters; no duplicate names ignoring case) and the native definition rules; else
DEPLOYMENT_RELEASE_INVALID(field=calendars). Days without periods are dropped, as storage keeps them. - Frozen review. One read per calendar (id, revision, default, content, owner) gives the disposition, the change summary
and a hash in the reviewed state and fingerprint. Without native calendar read authority here the review is
NOT_REVIEWABLEand admission refuses (DEPLOYMENT_CALENDARS_NOT_REVIEWABLE, 403); on an unmanaged workspaceUNMANAGED. - Drift. Before its step the calendar and owner must equal the frozen baseline (absent included, with a retained owner); after it, the expectation, and not the default. Resume, VERIFY and reconciliation check both.
- Disclosure. Calendar owners in the ledger list, runs that apply calendars, and Resume of such a run need native
calendar read authority in that workspace (neutral not-found otherwise). Ceilings:
PROCESS_CALENDAR_MANAGEandPROCESS_CALENDAR_VIEWat review, admission, every step and Resume. - Downgrade.
000458down refuses while calendar steps exist.
Preimages and step records (SCRUM-4557, DEP-18)
Every managed run seals what its target held before it changed anything, and every destructive step seals exactly what it
destroyed (migration 000460; spec specs/20261117-scrum-4557-dep18-preimages).
- Admission preimage.
startRunreads, in the run's workspace inside the admission transaction, one item per distinct family and key the run touches (VERIFY excluded): a rule's versions in full (with pin state and function), its active version, drafts, saved tests with their release classification, document-generation delegations and the data models a generated rule reads; a business function's record, native owner and function-scoped grants; a contract's record; a binding; the workspace settings as stored; a calendar's storage snapshot (row, weekly periods, every date row with its periods, identities and confirmation provenance); every item's ledger owner and this source's mappings;absentfor an item not here.DeploymentRunner.createinserts run, steps and preimage together; thecreatedaudit carries its hash. - Sealed text.
deployment_run_preimage(one row per run) keeps the canonical JSON text (keys sorted at every depth, exact decimals, no insignificant whitespace) as the authoritative payload, never JSONB;sha256is over its bytes and is checked on every read. Triggers refuse UPDATE, DELETE and TRUNCATE (DEPLOYMENT_PREIMAGE_IMMUTABLE); the primary key refuses a second capture. Resume and takeover never recapture. - Step records.
REVOKE_CONTRACT,RETIRE_RULE,DELETE_FUNCTIONandAPPLY_CALENDARwritedeployment_run_step_recordin their own transaction with the effect and the checkpoint, read under the effect's locks after the frozen comparison. A function removal first takes the workspace membership lock (the native grant writers' lock) and its baseline includes a fingerprint of the function's grants, so a grant changed before the step is drift and none can change between the record and the deletion. - Database guarantees. Deferred constraint triggers refuse to commit a run without its preimage
(
DEPLOYMENT_PREIMAGE_REQUIRED) and a destructive step APPLIED without its record (DEPLOYMENT_STEP_RECORD_REQUIRED), so an older application instance cannot admit an uncaptured run or apply a destructive step without recording it. The runner fails closed: a run whose preimage is missing or no longer matches its hash is CANCELLED before its first step. - Read.
GET /api/deployment/runs/{id}/preimagereturns{sha256, capturedAt, items:[{family, key, name, before}]}, all or nothing, only to a reader who may read the run, administers its workspace now (fresh), and holds each touched family's native view permission within the credential ceiling (rules, contracts and bindings, workspace view, calendars; the native settings and calendar read rules;DATA_MODEL_VIEWfor a generated rule's source models); otherwise the neutralDEPLOYMENT_RUN_NOT_FOUND.beforeisexisted, plus a contract's status, the settings values, or a calendar's zone, number of dates and working weekdays; never rule versions, binding targets, saved tests, delegations or access overrides. The run view carries the reader-specificpreimage: READABLE | NOT_READABLE | NOT_RECORDED. - Studio. "Before this import" (run view and completion) is offered only when READABLE, loads when opened, re-reads every 30 s while open, ignores answers for another run or session generation, withdraws on any refusal, and tells an outage (Retry) from a refusal.
- Upgrade and downgrade.
000460up locks the run table and refuses while any run is QUEUED, RUNNING or FAILED_PARTIAL (finish or abandon them first; no run is backfilled). Down locks the run and evidence tables, then refuses while any preimage or step record exists. Policy (FR-017): a failed run stays FAILED_PARTIAL with its evidence; restoring from it is DEP-18b.
The deployment write fence (SCRUM-4556, DEP-17a part 2)
While an admitted change (a release import or a ledger adoption) changes a managed workspace, the workspace is held. The hold is recorded in its own transaction before the change starts and removed when it ends, whether it committed or not. One hold per workspace: a second admission for a held workspace is refused (DEPLOYMENT_WORKSPACE_HELD, 409).
- While a workspace is held, these changes are refused before they write, unless they are part of the deployment that holds it: publishing, retiring and removing rules, data models, screens, processes, lifecycles, forms, connected systems and integrations; Make Live of a data model (checked before any connector work and again before its DDL) and retiring a live schema; screen, process and lifecycle draft saves; contracts, bindings and workspace transfer; renaming, moving, archiving or deleting the workspace; and its business functions. People see "This workspace is being changed by a deployment. Try again when it finishes, or ask a deployment administrator." A second deployment into a held workspace is refused too.
- Database guard (part 3, migration
000452). Draft saves and removals that write their tables directly are refused by the database itself for a held workspace: form, rule, screen, data model and record type, process, integration and connected system drafts, new or removed process versions (case design publication, model purge). The guard waits on the same writer lock, so a hold is never taken in the middle of such a write. The deployment holding the workspace marks its own transaction and writes through. People see the same plain sentence (409,DEPLOYMENT_WORKSPACE_HELD). Runtime data (process instances, records, executions) is never held. - Make Live runs its DDL holding the workspace's writer lock for its whole length, so a deployment cannot hold the workspace while a schema change is under way, and a held workspace refuses a Make Live before any DDL.
- A held workspace's Production class cannot be changed (Peer access shows the reason on the button).
- If the server stops part-way, the hold stays. Authorization → Deployment → Peer access lists Workspaces held by a deployment (workspace, what holds it, since when and who started it) for deployment administrators. Abandon hold asks for the workspace's name; abandoning is audited with the hold's details. Taking, releasing and abandoning holds are all audited as
DEPLOYMENT_WORKSPACE_HOLD_CHANGED(change: held, released, abandoned). Stored in migration000445. - Configuration and settings (part 4, migration
000453). The same guard covers configuration items and their values, provisioned credentials, business calendars (their periods and dates), the AI, publishing and deletion policies, reference data decisions, record operation definitions, rule test cases, and Home's workspace configuration and business-view definitions. Running a rule test, and the daily extension of a calendar's ledger, are not changes and go through. Never held: the credential vault (OAuth tokens refresh while processes run), records themselves (people and processes change them), and run-time logs and usage.
API: GET /api/deployment/workspace-holds and POST /api/deployment/workspace-holds/abandon with {workspaceId, holdId, typedName} (deployment administrators; a hold already gone answers DEPLOYMENT_WORKSPACE_HOLD_NOT_FOUND, 409).
Workspace deployment (operator manual)
Practical guide and worked examples
Treat release content, target admission and environment state separately
A workspace environment classification is not itself a deployment. A release is a signed content package with source identity, selected/whole scope, immutable entries/dependencies and compatibility information. A target independently admits trust, grants, ownership/ledger mappings, bindings and runtime references. A valid signature does not authorize an unreadable asset, a forbidden target import or a production operation.
Use a normal signed-in person with the actual deployment action grants and workspace roles. Release viewing/building/downloading have separate native admission; API-key/service-account identity and platform bypass are not substitutes for the required release grant. Check the deployment feature setting and the permitted asset families before preparing a package.
| Phase | Actual contract | What to retain |
|---|---|---|
| Select | Source workspaces/candidates visible to the caller | Source workspace ID and actual published root coordinates. |
| Build | BuildRequest(scope, roots, tombstones) |
Release ID/number/hash, entries, source and signing identity. |
| Download | Native signed format-4 bytes | Original file and hash; do not edit signed content. |
| Inspect | Current target plus original release | Compatibility/trust/dependency/ownership/binding findings. |
| Import/transfer | Exact admitted target and supported route | Resulting native import/deployment report and retained provenance. |
| Environment administration | Current revision and complete intended mutable draft | Old/new values, owner, type, transfer mode and accepted revision. |
An unknown response needs readback of the same actual state, not an invented generic idempotency field: the release build DTO does not expose a universal operationId. The detailed trust, signing, family, peer, ledger and portability sections below remain part of the reference.
The examples below use synthetic teaching data. They are grounded in the cited source contracts; this documentation change did not execute these operations against a running Inflow deployment. Use normal authenticated sessions and the actual returned identifiers, revisions and versions from an authorized environment.
Example ROOT-DEP-01 — Build a release from an authorized synthetic workspace
Scenario and inputs. Nadia is a normal signed-in person with the actual deployment BUILD grant and required workspace/asset read access. The synthetic People Operations workspace contains only the published assets intended for this exercise. She wants a whole-workspace signed release, not a snapshot of arbitrary drafts or private credentials.
Procedure. Read /api/deployment/releases/workspaces and the selected workspace's candidates first. Confirm the published scope and asset visibility. The release-build request is:
POST /api/deployment/releases?workspaceId=<actual-source-workspace-id>
Content-Type: application/json
{"scope":"WHOLE","roots":[],"tombstones":[]}
Inspect the returned summary, entries/dependencies and native download eligibility. For a SELECTED release, use actual candidate family/key/version references and its declared dependency closure instead of inventing a family name or silently substituting latest drafts.
Expected result. The resulting release records its source server/workspace, release number, content/hash/signing identity and supported published entries. Every unreadable required asset can refuse the build; a platform-wide role does not replace its deployment grant. Building a package does not change a target workspace or prove runtime compatibility there.
Failure and recovery. If the build reply is lost, inspect current releases and their actual content/report with the owner before another attempt. Do not add an unsupported idempotency field or assume matching content proves the same operation. Resolve missing grants/dependencies through their native owners, and never remove a difficult asset or secret reference merely to make the build appear complete.
Sources. DeploymentReleasesController.java:62, ReleaseService.java:125, ReleaseService.java:45.
Example ROOT-DEP-02 — Inspect original signed bytes before choosing target bindings
Scenario and inputs. A signed People Operations release has been downloaded through the native route. Nadia has an admitted non-Production target workspace and the required target authority. The source IDs differ from the target's identities/connections, so matching display names are insufficient to prove a valid or authorized rebind.
Procedure. Retain the original downloaded bytes and their hash. Select the actual target workspace through the current workspace context. Use the native release-inspection surface, whose request wraps the exact downloaded ReleasePackage in release, and read compatibility, signature/trust, family, dependency, ownership/ledger and binding findings. Use permitted target discovery to resolve aliases to actual target contracts. Do not manually reconstruct a smaller release object or edit a source ID inside the signed file to make it look local.
Expected result. Inspection explains what this target can admit and which references need resolution before an import. A verified package signature establishes the signed content identity, not permission for the target operation or availability of every provider/template/runtime dependency. Source and target resource IDs remain distinct coordinates with explicit native mapping/provenance.
Failure and recovery. On an unknown signer, unsupported family, unreadable dependency or conflicting ownership, preserve the package and resolve the exact target admission issue with its owner. Do not trust an arbitrary new signing key, rewrite the signature/hash or use another workspace's bindings to bypass a refusal. No import should be inferred from a successful inspection alone.
Sources. DeploymentReleasesController.java:28, ReleaseWorkspaceImport.java:90, WorkspaceTransferController.java:49.
Example ROOT-DEP-03 — Resolve a stale environment edit without discarding another owner’s settings
Scenario and inputs. An authorized deployment administrator is editing an existing environment's display details while another administrator changes its owner or transfer configuration. The editor has an old revision. Environment definition, workspace classification, source trust and actual transfer execution are separate records; changing one must not silently overwrite the others.
Procedure. Read the exact environment through its native API/UI and retain all editable fields: key/display name, actual type, transfer mode, base URL, colour and owner. Submit the complete intended draft with the current expectedRevision through the supported environment update. If it is stale, reload and compare the other administrator's changes before deciding what to retain. Re-evaluate owner eligibility and target URL/trust instead of copying an earlier GET response wholesale with derived health/history fields.
Expected result. The service uses an explicit revision fence. A missing revision is reported as a structured stale environment outcome rather than a silent unconditional update. An accepted edit returns the new definition/revision and owner display metadata; it does not assert that a connection test or deployment transfer has succeeded.
Failure and recovery. Do not increment the number locally, omit another owner's settings or disable trust checks to force the update. If the base URL or owner is unavailable, ask the accountable environment owner to resolve it. Production retirement also has its own exact-name confirmation; an ordinary display edit is not authorization for that separate consequential lifecycle action.
Sources. DeploymentEnvironmentController.java:38, DeploymentEnvironmentController.java:96, DeploymentEnvironmentController.java:132.
Example ROOT-DEP-04 — Respect a Production package-import refusal
Scenario and inputs. A signed release is valid, but an operator selected a Production or otherwise disallowed target on the direct workspace package-import path. The operator must distinguish content validity from target policy. A workspace's lifecycle label or a broad platform permission does not convert a forbidden import into an approved rollout.
Procedure. Read the selected target's current workspace/environment and the exact refusal from the native transfer boundary. Inspect which route was used: /api/workspaces/import accepts either the supported legacy export package or the signed release, with mutually exclusive fields and actual bindings. The controller calls target admission before importing. Use the documented owner-approved deployment workflow only where that target and route are currently admitted; retain the original package and its hash rather than modifying it to evade the classification.
Expected result. A known target refusal prevents this direct import, even when the release signature is valid. Content verification, workspace Admin authority, deployment grants, managed ownership and Production restrictions are independent checks. The refusal and original evidence remain part of the operating history, not an empty successful import report.
Failure and recovery. Do not relabel Production as DEV, delete ledger ownership, use the legacy package field as an alternate bypass or borrow an administrator identity. If no rollout route is admitted for the intended target, keep it untouched and ask its authorized deployment owner for the concrete next action. This documentation does not resume private/native/R5 or other held qualification proofs.
Sources. WorkspaceTransferController.java:79, WorkspaceTransferController.java:84, DefaultWorkspaceTransferService.java:1.
Workspace deployment moves a workspace's published design from a development server to destination servers (Test, UAT, Production, and others). Every setting is managed from Studio admin pages, and every decision is made on the server. The full specification is in specs/481-workspace-deployment/, and the epic is SCRUM-4532.
This manual grows with each delivered ticket. The current state is described below.
Status
| Capability | State |
|---|---|
| Deployment foundation (DEP-01, SCRUM-4533) | Delivered: the server-side module, the deployment grants and authority, and safety utilities. No user-visible feature yet. |
| Deployment permissions page (DEP-02, SCRUM-4534) | Delivered: Authorization → Deployment → Permissions. |
| Environments (DEP-03, SCRUM-4535; owner as a person, SCRUM-4603) | Delivered: Authorization → Deployment → Environments. |
| Pairing and request signing (DEP-04, SCRUM-4536) | Delivered: Authorization → Deployment → Trust, and Pair / Issue pairing code on Environments. |
| Peer access: grants, production class, server status (DEP-04a, SCRUM-4537) | Delivered: Authorization → Deployment → Peer access, and Check status on Trust. |
| Outbound access: allow-list of private destinations (DEP-04b, SCRUM-4538) | Delivered: Authorization → Deployment → Outbound access. |
| Signing keys and trusted signers (DEP-05, SCRUM-4539) | Delivered: Authorization → Deployment → Signing. |
| Signed releases, package format 4 (DEP-06, SCRUM-4540) | Delivered: Authorization → Deployment → Releases, and signed release files in workspace import. |
| Workspace targets on destination servers (DEP-12 part 1, SCRUM-4549) | Delivered: workspace → Deploy → Deployment targets. |
| Release distribution to destination servers (DEP-12 part 2a, SCRUM-4549) | Delivered: workspace → Deploy → Release distribution. Enforced when the workspace is created on the target, and later by job claims and release fetches. |
| Create the workspace on the target (DEP-12 part 2b, SCRUM-4549) | Delivered: Deployment targets → Create there, push environments only, behind the release flag. Pull-mode creation jobs arrive with DEP-16. |
| Deploy, rollback | Not yet delivered (DEP-06a onward) |
The release flag
All operational deployment routes are behind one server setting:
inflow.deployment.release-enabled=true
The routes are: creating a workspace on a target, deploying, rolling back, pushing, uploading and promoting.
- Default: off. The canonical file accepts strict
true/falsevalues; malformed values refuse configuration. Activation requires restart. - Server scope: workspace-scoped editors cannot switch it on. An authorized global platform administrator may edit the canonical server value through native HTTP/MCP; system administrators may use the coordinated file-edit procedure.
- When off: every operational route refuses with the outcome
DEPLOYMENT_RELEASE_DISABLEDbefore it changes anything. - Planned use: it stays off until the Phase 1 integration gate (DEP-P1G) passes.
Deployment grants
Deployment access is deny by default. A person may perform a deployment action only when all of these hold:
- They are signed in with a currently admitted user account: it exists, is active and is not locked. Service accounts arrive with deployment tokens (DEP-27).
- When the request uses a deployment token, the token's scope covers the environment, the action and the workspace. Tokens can never approve.
- They, or a group they belong to (including inherited groups), hold a deployment grant for that environment and action. A grant can also name
*, meaning every environment. - For an action that touches a workspace, they already hold at least this role in that workspace, and, for every asset the action touches, that asset family's permission and object access. One denied asset denies the whole action:
| Action | Minimum workspace role |
|---|---|
| View | Viewer |
| Build, Deploy, Approve, Roll back | Editor |
| Admin | Admin |
A deployment grant never widens workspace access, and platform bypass does not replace a deployment grant.
Grants are stored in deployment_permission_grants (migration 000379). Grants are administered from the deployment permissions page, which arrives with DEP-02. Every decision reads the grants fresh, so a revoked grant applies to the next request.
Pairing servers (trust)
Two servers trust each other only after an administrator on each side confirms the pairing. Pairing creates identity only: what a paired server may do comes later, from target-owned peer grants (DEP-04a). Until then, inventory and health stay refused even between trusted servers.
Configure each server
Each server that takes part needs two settings:
inflow.deployment.server-name=Inflow Production
inflow.deployment.public-base-url=https://prod.example.com
- Server name: up to 80 letters, digits, spaces and
._()-. - Public base URL: the https address other servers use to reach this one. Requests are verified against this address, not against proxy headers, so it must be exactly what peers call.
If either setting is missing or invalid, the Trust tab shows Not configured, and pairing refuses with DEPLOYMENT_TRUST_NOT_CONFIGURED. Calls to another server go through the outbound URL policy, so a peer on a private network must be on the enterprise allow-list.
Pair a target this server can reach (push)
- On the target, an administrator chooses Accept a source on the Trust tab. The code is shown once. It works once, for 15 minutes, and locks after 5 wrong attempts.
- On the source, an administrator chooses Pair on the environment and enters the code. The source calls the target.
- Both pages now show the link as Waiting for confirmation, with both key fingerprints. The two administrators compare the fingerprints by phone or in person. Each presses Fingerprints match, confirm only if every group matches.
- The link becomes Trusted on both sides only after both have confirmed.
Pair a target that cannot be reached (pull)
- On the source, an administrator chooses Issue pairing code on the pull environment.
- On the target, an administrator chooses Pair with a source on the Trust tab and enters the source's address and the code. The target calls the source; the source never connects to the target.
- Confirm as above.
The side that called (the initiator) syncs with the other side every minute. Confirmations, key rotations and revocations made on the other side reach it within a minute. Check now syncs at once.
Pull jobs (SCRUM-4558, DEP-17b part 1)
A PULL environment is never called by its source (DEPLOYMENT_TARGET_PULL_ONLY), so it needs no address. Its transfer mode is fixed at creation (DEPLOYMENT_ENVIRONMENT_MODE_FIXED), checked by the service and by a database trigger. Work reaches it as jobs it pulls. This part offers server HEALTH and INVENTORY only. Workspace jobs, creation, comparison and deployment over pull come in later parts. Until then, the target directory, configuration pickers and credential checks, and comparisons answer "not available over pull" without any call.
- Source routes (signed, one operation each):
POST /api/deployment/peer/jobs/claim(JOB_CLAIM: a check-in;{take}asks for a job when the target has a free slot),/{id}/renew(JOB_RENEW),/{id}/events(JOB_EVENTS: at most 12 fixed phases) and/{id}/result(JOB_RESULT: SUCCEEDED with the kind's exact typed answer, or FAILED with an allow-listed code). They are answered with signed{outcome: OK | STOP | RETRY, code}. Bodies are capped before parsing at 4 KiB (claim, renew), 8 KiB (events) and 256 KiB (result). - Administration:
GET /api/deployment/pull/environmentsreturns each PULL environment's pull view (canRun, pairing, last check-in, last health and inventory), only for readers who may view it.POST|GET /api/deployment/environments/{key}/jobs,GET …/jobs/{id}andPOST …/jobs/{id}/cancelmanage jobs. Reading needs deployment administration plus deployment VIEW in the environment; running and cancelling also need deployment ADMIN there. A job the reader may not see answers 404. - Limits and lifetime: one open job per kind and at most 20 per environment; 24 hours to be claimed (
DEPLOYMENT_PEER_JOB_EXPIRED); 60-second leases; 3 attempts (…_ABANDONED); 10 minutes of run time (…_TIMED_OUT). The source sweeps every minute (inflow.deployment.pull.sweep.enabled). Trust loss fails open jobs at once (DEPLOYMENT_PEER_LINK_REVOKED). The source re-checks the requester at claim and renewal (DEPLOYMENT_PEER_JOB_REQUESTER_NOT_ALLOWED);DEPLOYMENT_PEER_NOT_GRANTEDon a pull job means the environment's own grants refused it, and Studio marks it Refused. - Target poller (
inflow.deployment.pull.enabled): every 15 seconds each pulling link checks in once; a link is never queued twice. Pull calls use their own transport: three lanes per link (check-in, lease calls, trust sync) and at most 192 threads. A stuck call keeps only its own lane until it exits. A call that waits for a free thread shows its link as Waiting for transport capacity on Trust; if no thread frees up before its deadline it ends asTRANSPORT_BUSY(the source was never asked), never as unreachable. Execution has 4 slots per node, one per link; a freed slot goes to the link that has waited longest, across nodes. The target admits each job with its own SERVER peer grant, answers inventory from a snapshot refreshed every five minutes, and stops within its own 10-minute budget, whatever the source answers. - Pairing capacity: a target pulls from at most 64 sources (
DEPLOYMENT_PULL_LINK_LIMIT). Pairing is also refused while stuck calls hold the lanes a new link needs (DEPLOYMENT_PULL_TRANSPORT_BUSY). Both refusals happen before any call. A pairing whose answer was lost stays Waiting to hear from a source (its key and its place kept) until an administrator abandons it. - Legacy pairings: a PULL environment whose link was made by this server calling it is
pull.pairing = INCOMPATIBLE; jobs are refused (DEPLOYMENT_PULL_PAIRING_NEEDED). Revoke it if it is trusted, or Withdraw it if pending (local, audited), then issue a pairing code. - Audit:
DEPLOYMENT_PEER_JOB_CHANGED(queued, claimed, answered, failed, cancelled, swept), with ids and codes only.
Rotate and revoke
- Rotate key, on either side, creates a new key for that link. The old key keeps working until the other side has switched, so nothing is interrupted. The fingerprints shown change on both sides.
- Revoke, on either side, needs the other server's name typed. The link is refused at once on that side, and on the other side at the next sync. A revoked link cannot be restored; pair again with a new code.
- A link that is not confirmed within 60 minutes expires. Pair again with a new code.
Every change, and every refused request from a known link, is audited as DEPLOYMENT_TRUST_CHANGED. The audit records statuses and fingerprints, never keys or code secrets.
Troubleshooting
| What you see | What it means |
|---|---|
| The pairing code was not accepted | The code is mistyped, already used, expired, withdrawn or locked. Ask for a new one. |
| The other server could not be reached | Check the address, that the peer's certificate is valid, and the outbound allow-list. |
| The other server answered, but not as an Inflow server would | The address points at something else, or the peer runs an incompatible version. |
| Last check could not reach the other server | The initiator's latest sync failed; the link keeps its state until the next one succeeds. |
Peer access (grants)
Pairing only proves who a server is. What a paired server may ask this server to do is decided here, on the server that receives deployments, under Authorization → Deployment → Peer access. Every request from a paired server is refused unless an active grant allows it, and every refusal is audited.
Grants
Add grant names a paired server (a trusted server that deploys to this one) and what it may do:
| Grant | Allows | Acts as |
|---|---|---|
| Server status | Health, platform version and installed plugins of this server. Nothing from any workspace. | Nothing: it only reads. |
| One workspace | Chosen operations (compare, deploy, roll back, health, inventory) on one existing workspace of this server, for one workspace of the other server, which you pick from its list. | A service account of this server, chosen in the dialog. |
| A new workspace | Creating exactly one workspace here, for a workspace of the other server (picked from its list), under a key of this server. The key starts as the other server's key when that key is free here; any free key of the workspace-key rule can be chosen instead (the other server maps its workspace to it under Deployment targets). When it is created, the reservation becomes a One workspace grant for it. | A service account of this server. |
- The service account is the local identity that publishes what is deployed; the other server never receives authority on this server. Only active service accounts can be chosen, and a grant whose account is later disabled stops working and shows Inactive.
- Accept approvals made on the other server lets later approval steps accept signed approvals from the other server's mapped approvers. Off by default: approvals are made on this server.
- Nothing is typed. The other server's workspaces (names and keys only) are read from it over the signed link when the dialog opens. If it cannot be reached, the dialog says why and offers Retry. When the grant is saved, the server checks the picked workspace against a fresh read.
- A server can hold one Server status grant, one grant per workspace, and a key can be reserved once. Change a grant's operations, account or approval setting with Change; Revoke ends it at once.
- A grant on a pairing that is no longer trusted admits nothing.
Production class
Each workspace of this server is Production or Non-production for deployments into it. This server decides, whatever the source server calls the environment. A workspace that has not been declared is treated as Production, so a deployment into it needs a typed Production confirmation here. Use Declare Production or Declare Non-production; the change is audited.
Check status (source side)
On the server that deploys, Trust → Check status asks the paired target for its health and inventory over the signed link. The row then shows Connected, the target's platform version, its plugin count and the time of the check. Until the target grants Server status, it shows Not allowed to read the other server's status yet.
The platform version is the operator-configured inflow.platform.version when set, otherwise build and the first 12 characters of the build commit.
Outbound access (private destinations)
Every request this server makes for deployment goes through the outbound policy: HTTPS with a valid certificate, no redirects, the exact address that was checked (no DNS rebinding), and bounded answers and deadlines. Public addresses need nothing. Private and internal addresses are refused unless they are listed under Authorization → Deployment → Outbound access:
- Allow a destination lists, to pick from, the hosts of this server's paired servers and of the environments whose connection test was refused or has not run yet, with each one's last test and anything already allowed. Another destination takes a host name that is not listed (for example
plant.internal.example), a single address (kept as a one-address range) or an address range (for example10.20.0.0/16; at least /16, or /48 for IPv6). Then choose what it is allowed for, which is preselected for a picked destination, and give a reason:- Connection tests: the Environments tab's Test connection;
- Pairing and server checks: pairing, keeping a pairing in step, and Check status.
- An allowance opens a destination only for what it is allowed for, and never relaxes HTTPS, certificate checks or address pinning.
- Loopback, link-local (including the cloud metadata addresses 169.254.169.254 and fd00:ec2::254), unspecified and multicast addresses can never be allowed, nor IPv6 forms that carry a non-public IPv4 address (NAT64, 6to4, IPv4-mapped) or that cannot be checked (local-use NAT64, Teredo). An allowed host name that later resolves to one of them is still refused, even within the same request. Entering one is refused with that reason on the field, not as a format error. Each allowance shows who added it and when.
- Remove takes effect with the next request. Every change is audited with the reason.
Each allowance shows who added it (name and username) and what it is used by: the environments and paired servers whose address it covers (a host name exactly; a range, every address-literal host inside it). Destinations that need an allowance lists this server's environments and paired servers on private addresses that are not allowed yet; Allow… opens the dialog on that destination. A destination that can never be allowed is refused with its specific reason first (for example, the cloud metadata address), and Allow stays off until the destination changes.
The server-wide INFLOW_CONNECTOR_OUTBOUND_ALLOWLIST setting still applies to every outbound feature. Outbound access applies to deployment only.
Which server am I on? When INFLOW_DEPLOYMENT_SERVER_NAME is set, the Studio header shows the server's name next to the workspace environment badge (which then reads, for example, "Workspace DEV"), so a workspace's tier is never read as the server's.
Signing (keys and trusted signers)
Releases are signed by the server that builds them and checked by the server that receives them. Authorization → Deployment → Signing has two parts.
This server's signing keys (the side that builds releases):
- Generate a signing key creates an Ed25519 key. Its private half is created in the credential vault and never leaves it: it is not shown, downloaded, logged or audited.
- Activate makes a key the one that signs. Exactly one key is active. Activating another key retires the current one, and releases it signed stay valid.
- Retire stops a key from signing anything new. Until another key is active, this server cannot sign releases.
- Public key downloads
inflow-signing-key-….json, holding the server name, the key's fingerprint and its public key, for a receiving server that cannot reach this one.
Signers this server trusts (the side that receives releases):
- Trust a key from a paired server reads the keys of a paired server that deploys to this one over the signed link. Compare the fingerprint with the one its administrator sees on their Signing tab, tick the confirmation and choose Trust key.
- Import a key file is for an air-gapped server. Choose the file, then type the fingerprint the other administrator gave you separately, for example by phone. Do not copy it from the file. A wrong fingerprint is refused and nothing is trusted.
- Retire a signer when the other server rotated its key: releases it signed stay valid.
- Mark compromised (type the first 8 characters of the fingerprint) refuses every release signed by that key from now on, whatever signing time it claims. The only exceptions are releases this server had already accepted. This cannot be undone.
Every change is audited with fingerprints and statuses only, never key material.
Releases
A release is a signed, numbered, unchangeable copy of a workspace's published design, built on the server that holds it. Releases are kept on that server (migration 000403); their content is stored once per content fingerprint.
What a release holds. The registered families include business functions,
processes, rules, legacy forms, contracts/bindings, lifecycles, rule test suites,
data models, reviewed reference data, workspace settings, business calendars,
connected systems, integrations, fabrics, document-generation templates, themes
and interface kinds. The sections below describe their distinct portability and
selection rules; DeploymentAdministrationConfiguration and the asset-family
registry are authoritative for the current binary. Each design item is a
published version with its family, key, version and fingerprint; drafts are
not silently published for export. Only explicitly reviewed reference datasets
carry admitted record values. Secrets, runtime cases, arbitrary records and
documents, audit history and group memberships do not become release payloads.
Credential-like content refuses the build before signing.
Building (Authorization → Deployment → Releases, choose the workspace, Build a release):
- The whole workspace releases the latest published version of everything.
- Selected assets releases only the assets you choose.
- Either way, every exact version an item depends on is added automatically: a process's pinned rules, sub-processes and forms, any asset's business function, and a contract's target. Dependencies are read from rule steps, sub-process and process-start steps, aliases, expression fields (including timers) and form expressions. A dependency that is not published refuses the build and names it. An older version kept only because something pins it is marked "needed by …": it travels without changing which version is active on the receiving server.
- The release is numbered per workspace, compared with the previous release (its baseline), and signed with this server's active signing key (see Signing). Without an active key nothing is built.
- Removals are never implied: an asset left out of a release is not deleted anywhere. Explicit removals (tombstones) are part of the format and arrive in Studio with the release builder (DEP-15).
- Limits: 8 MiB per item, 64 MiB and 5,000 items per release.
Who may do what. Seeing releases needs a deployment grant for View in any environment and at least Viewer in the workspace. Building and downloading need Build in any environment, Editor in the workspace, and read access to every item in the release; one unreadable item refuses the whole build. Opening and downloading check that access again, so a release is never shown or handed out with an item its reader cannot open today, and Selected assets offers only items the person can read. The tab is part of the Deployment section, so today it is reached by deployment administrators; release grantees who do not administer deployment get access with SCRUM-4650 or the workspace's own Deployment tab (DEP-15). Every build and download is audited (DEPLOYMENT_RELEASE_CHANGED) in the release's own workspace, with the release number, fingerprint, scope and item count, never content. Someone who may build but not view sees the workspace with Build a release only.
Opening a release shows what it holds and why each item is included, what changed since the baseline, the drafts left out, the signing key, the release fingerprint, and what the receiving server needs: the same major Inflow version and at least the release's minimum version, plus any required plugins at their minimum versions. A newer receiving server than the one the release was tested on is accepted with a warning. The platform version is inflow.platform.version when it is a semantic version, otherwise the version the platform was built as.
Lifecycles (DEP-07). A process version published as a lifecycle carries its lifecycle: the states and transitions, the exact version of each state's flow, the subject binding and the description. Each state flow travels too, at its exact version. The lifecycle has the process's key and version. Server-local details (the draft, its revision, the publication time) stay behind.
Rule test suites (DEP-07). When a release carries a rule's current published version and the rule has saved test cases, the suite travels with it, bound to that version (older versions that travel only because something pins them carry none). A suite carries each case's name, inputs, expected result, assertion and fixture data, and never the case's identifiers, run history, the source's execution identifiers or its evidence tags: the receiving server derives its own evidence under its own key when it applies the suite.
Test data decides whether a suite may travel. On the rule's Test this Rule step, each saved case has a Test data choice:
- Synthetic — may travel in releases: invented test data. It travels with the rule.
- Keep on this server: the case stays here; the suite records only how many were kept.
A hand-written case starts with no choice. Data captured from a real run always stays on this server and needs no choice (it shows as kept); until masked copies are possible (DEP-08), only hand-written cases travel. The receiving server's review says how many cases travelled and how many stayed on the source server. Building a release that would carry a case without a choice is refused before anything is signed (DEPLOYMENT_TEST_DATA_UNCLASSIFIED), naming the rule and how many cases need a choice. Making the choice needs the right to edit the rule and is audited (RULE_TEST_CASE_CLASSIFIED, old and new value). Masked copies of real data arrive with the masking pipeline (DEP-08).
Lifecycles and test suites are not offered as separate choices under Selected assets: choose the process or rule, and they come with it. A rule with undecided test data does not block releasing other assets.
On the receiving server, the import review names lifecycles and rule test suites ("Tests of <rule>", with the number of cases); like processes, they are applied by a governed deployment (DEP-17), so a release that holds them is reviewed but not imported here.
The release records the source workspace's display name, so the receiving server says "Release 3 of Airline operations". Releases built before this keep showing the workspace key.
Data models (DEP-08). A release carries published data-model versions: each record type and field, with its version number. Connector bindings and sync settings of bound record types never travel: they are environment configuration, mapped on the receiving server. When a release holds a data model, the receiving server's review compares it with that workspace's own published version of the same model:
- Additive changes keep every existing record and use valid: a new record type, a new optional field, a new required field with a default, new enum values, a longer text length, a uniqueness rule dropped, an optional relationship added (or a required one on a new record type), changed indexes, a changed default.
- Breaking changes need a migration plan: a removed record type or field, a changed field type, a field made required, a new required field without a default, removed enum values, a shorter length, a rename, a field made unique, a changed record key, a removed or changed relationship (including what forms and grids may change on it), a new required one, a new or tightened unique index, or a required field losing its default. Any other setting that travels, such as retention or how a field is written, is listed and treated as breaking, because the review cannot tell whether it restricts existing data; moving boxes on the diagram changes nothing. A text field without a stated length is stored at 255 characters, so that is the length compared.
For each breaking change the review counts, from the receiving server's own data, the records it affects (for example "120 records here hold one of these values"), and how many assets there use the model, by kind (for example "Used here by 2 rules and 1 screen"); each asset counts once, and no asset is named. A count of a renamed field or type is made under its current name on the receiving server. A count the server cannot make, or one you may not see, reads "not counted"; so does any count for a record type that keeps archived records, because those would not be included, and for a model that is live in more than one database. Data models are applied by a governed deployment. Choosing a data model as a release asset, or seeing the receiving workspace's version of it, needs the permission to view data models and access to that model.
Platform enumerations (DEP-08). Enumerations are a platform catalog (conf/enumerations), not workspace assets. A release declares the enumerations its processes' service tasks use, at the version the building server has. A receiving server without one of them, or with an older version, refuses the release before anything is imported (DEPLOYMENT_RELEASE_INCOMPATIBLE, ENUMERATION_MISSING or ENUMERATION_TOO_OLD).
Reference data (DEP-08). Reference data is the records of a record type that every server needs alike, such as airport codes or currencies. On Deployment → Reference data, choose a workspace; every record type of its published data models is listed. Someone who may build releases for the workspace and administer that data model chooses Choose to mark a type as reference data that travels, and decides for each field whether its value travels or is withheld:
- Personal fields and confidential or restricted fields are withheld by default; everything else travels. A withheld value never leaves the server: the field is named in the release, without a value.
- Columns the platform keeps (the record id, timestamps) and references to records, users, groups, documents or folders never travel: they hold this server's own ids.
- The natural key always travels, because the receiving server matches records by it. A type without a natural key, or one whose records live in a connected system, cannot be reference data.
- Each change is recorded in the audit log (
DEPLOYMENT_REFERENCE_DATA_CHANGED, the old and new choices, never values).
Every release of the workspace then carries the type's records (at most 10,000), sorted by the natural key, without record ids. A build is refused, and nothing is signed, when a type chosen for a release is not marked as reference data, a field has no decision (for example one added in a later model version), the natural key is withheld, the records cannot be read, or there are too many. Records are read with the building person's own record access. On the receiving server, the review compares the records with its own by natural key: how many are new, changed, unchanged, and present only there. Reference data is applied by a governed deployment.
Fabric definitions (DEP-10). A published Fabric definition can be chosen for a release, or travels with the dashboards and forms that read it. It carries its types at its exact version and depends on what they read:
- a local type, on its data model (the pinned version, or the current one);
- a table or document bound to a connected system of the workspace, on that system, named by key. The table name inside that system travels; the system's address is supplied on the receiving server (see below);
- an API-bound type, on its integration, named by key and version.
Who authorized replication never travels: the receiving server re-validates the definition and re-authorizes it under its own publisher when a governed deployment applies it. A release is refused when a type is bound to the platform's own data store or to something the workspace does not publish, or when the definition holds an address or an id of this server. Building needs permission to view the Fabric definition (FABRIC_VIEW, on the object).
Workspace settings (DEP-11). A workspace's settings can be chosen for a release as one item; a whole-workspace release carries them too. Only an allowlist travels: the AI policy (whether AI features are on, the allowed AI models and providers by their registry names, and the monthly token limit), publishing governance (Require published artifacts for Live, Require Live for Automations) and the deletion policy. Each travels as the value in effect, so a setting never changed travels as its default. Never carried: the workspace's identity (id, key, name, members, roles), API keys, usage figures, its environment, the AI image approval (which names the person who approved it) or feature switches (set per environment). The review on the receiving server says which settings the release would change in that workspace, for example "Monthly token limit from unlimited to 500,000", for someone who may view that workspace; a governed deployment applies them. A release is refused when an allowed AI provider or model is named by an id of this server. Building needs permission to view the workspace (WORKSPACE_VIEW).
People in processes (DEP-11). A process names the people its tasks go to only by reference, never by this server's ids. A user travels by username, a group by its key and a role by its id, for example "group air-flightops" or "user res02". Groups, roles, members and grants never travel. The review on the receiving server lists, for each process, the people that server must map ("Needs these people mapped on this server: group air-flightops, user res02"). Each one is mapped there to one of its own users, groups or roles through a principal binding; nothing is matched by name. Until it is mapped, the task goes to nobody and the step fails, rather than going to the wrong person.
A release is refused, and nothing is signed, when:
- a task goes to a user or group this server no longer has;
- a group value is ambiguous;
- any other step names a fixed person, group or role, such as a step that adds members to a fixed group, a quoted user name, or a fixed notification audience. Use a variable or an expression instead.
Business calendars (DEP-11). A business calendar can be chosen for a release, and travels with every lifecycle whose service level is measured with it. It travels by its name, with its time zone, working week, holidays and exceptions; a holiday still to review travels as one, so it is reviewed there too. It never carries this server's ids. A lifecycle that follows the workspace's default calendar needs none: on the receiving server it follows that workspace's own default. The review on the receiving server lists each calendar with its time zone, its number of holidays and exceptions and how many are still to review, and says when it was the default calendar on the source server. A governed deployment matches each calendar there by name; the review says whether that workspace already has a calendar with the name (which would be updated) or not (it would be created), for someone who may view that workspace's calendars. A release is refused, and nothing is signed, when a lifecycle names a calendar that the workspace no longer has. Building needs permission to view the calendar (PROCESS_CALENDAR_VIEW).
Document rules and their templates (DEP-10). A published document rule travels with the template file it fills in, at the exact file it was published with. On the receiving server the review names the template after the rule, with its file type and size, for example "Word document · 38 KB", and states that the rule "Needs an output folder on this server for the documents it creates" when it writes into a fixed folder. That server checks the template before showing it: the file must be the one the rule pins, and a valid Word or Excel template there.
The release never carries this server's document, version or folder ids. A fixed output folder becomes a location the receiving server supplies; a folder chosen from a rule input travels as that input. The rule's approval does not travel either. The review of its preview, its certificate and its delegation belong to this server: on the receiving server a governed deployment publishes the rule again, under that server's own reviewer and grants (DEP-17).
A release is refused, and nothing is signed, when:
- the template can no longer be read in this workspace;
- the stored file no longer matches the one the rule was published with;
- the file is not a valid template;
- the file is larger than 6 MB;
- the template text holds something that looks like a password or key;
- a fixed value holds an id of this server;
- a constant names a document, folder or cabinet (documents stay on their server).
Building needs permission to view the template's document (DOCUMENT_VIEW, on the object), as publishing the rule did.
Connected systems and integrations (DEP-10). A published integration can be chosen for a release. It travels with the connected system it calls, both at their exact published versions and named by key. A connected system can also be chosen on its own. No connection value travels. The release never carries an address, host, port, database name, configuration value, credential or vault reference, and never an id of this server. Instead, each connected system says what the receiving server must supply: its connection settings (marked as addresses or plain settings, and whether each is required) and, when it signs in, a credential from that server's vault. The import review states this for each system, for example "Needs 4 connection settings (all addresses) and a credential from this server; their values never travel." The settings are supplied there before a governed deployment applies the system (DEP-13, DEP-14, DEP-17). Values the connector template supplies itself (driver, dialect, brand) are not listed; the receiving server takes them from its own copy of the template.
Connector templates are a platform catalog, like enumerations. A release only names the template version each connected system was published on. A receiving server whose catalog lacks that exact version refuses the release ("needs version 4 of the connector template postgresql, which this server does not have"). Building needs permission to view the connected system and the integration (CONNECTOR_VIEW, on each object).
A release is refused, and nothing is signed, when:
- a connected system names a template without a version (set up before templates had versions; publish it again);
- its capabilities hold an address or an id (a web address, an IP address, or a host or port setting);
- its address is in a form whose server name cannot be read, or a setting's name holds an address or an id;
- its name or description repeats a connection value, its address or host, or an id (for example the database name). Describe the system without them, publish again, then build;
- an integration calls a connected system the workspace does not publish (a platform system);
- an integration's definition holds an id of another object of this server, or an address (a web or IP address in a default, a request value or its details, or a value for an input or request field named like an address, at any depth, such as a host inside a request body).
An interface or process that calls an integration still cannot be released; that follows in a later step.
Record operations (DEP-09). A published record operation (for example "Close airport") can be released on its own or travels with the interfaces that run it. It carries its data model at the exact version it was published against, named by key, never by this server's id; an interface that names the operation with a formula cannot be released. Building needs permission to view that data model. A process whose task opens an interface form carries that form at the version the task pins.
Interfaces and themes (DEP-09). Published dashboards, forms and app shells can be chosen for a release, each at its published version. An interface brings what it uses: the interfaces it embeds or opens, the rules it runs, the data models its lists and forms read (at the exact versions it was published with), its business function, and its theme. A theme made in the workspace travels with the interface, by its name; a built-in theme is only named, and a receiving server without it refuses the release ("uses the built-in theme ..., which this server does not have").
A release never carries this server's own ids. Where an interface names a data model, one of its published versions or a workspace theme by id, the release names it by key and version instead, and the receiving server puts its own id back; links into this workspace (/workspaces/<key>/...) point at whichever workspace receives it. If an interface refers to something another server could not resolve — a document cabinet, a person written into a formula, an integration (DEP-10) — the build is refused, nothing is signed, and the message names the interface and what it refers to. Remove or replace that reference, publish the interface again, and build again. The same refusal applies to a Fabric data source (releases carry Fabric with DEP-10), an older form data setting that names a data model only by its record type, and a link or formula whose target is put together while the interface runs. Preview rows that a chart or a connected grid keeps for the designer never travel: on the receiving server the interface reads its own data. Building needs permission to view each interface and each workspace theme. On the receiving server, the review lists each interface by kind and title and each theme by name; interfaces and themes are applied by a governed deployment.
Download release file saves <workspace>-release-<n>.inflow-release.json (package format 4).
Importing a release (format 4)
Workspace import (Workspaces → Import process/rule package) accepts a release file as well as the earlier export formats 2 and 3. Before anything is imported, the receiving server checks, in this order:
- the signing key is one it trusts (Signing). A retired key is accepted; a compromised key is accepted only for releases this server had already admitted;
- the signature matches the release's exact list of contents;
- every item matches its fingerprint, with nothing missing or extra;
- this server is compatible.
The review shows the source server, release number, signer and contents. Any failure is a refusal in plain words, and nothing is created. The import then runs exactly like a format-3 import: it validates first and fails whole, re-binds dependency aliases, needs the workspace Admin role, and is audited.
The deployment ledger (DEP-06a). A release without processes or legacy forms is applied through this workspace's deployment ledger, which remembers, for each source (the trusted signer that signed the release — its pairing link, or its key when it was trusted from a file — and the source workspace's key), which version of each asset became which version here:
- Versions are mapped, not copied. Each rule version is published as the next version here; a source's rule v3 may become version 2 here. Rules are published in dependency order, and their exact pins (
rules:fee@3(…),rule('fee', 3)) are first rewritten to this server's version. Pins to "the current version" are left alone. Contracts that point at a rule version are mapped the same way. - Several versions of one rule in a release map separately (for example the current version as a root and an older version a caller pins).
- Activation is explicit. A version the release activates becomes the active one. A version that travels only because something pins it ("needed by …") is reused when this workspace already has it; otherwise the release needs a governed deployment, which can keep that version out of the active one without changing impact records.
- Rotating an offline key starts a new source. For a paired server the ledger follows the link, so rotating its signing key changes nothing. For a key enrolled from a file, the ledger follows the key: after rotating it, assets the old key created show as owned by another source. Pair the servers where you can; carrying ownership to a successor offline key is planned.
- Impact governance stays in charge. A new version of a rule that other assets here use needs an impact review before it is published, so such a release is left to a governed deployment too. The review names each such item and why.
- See the ledger. On Workspaces, Deployment ledger (next to Import release or package, for the same people) lists, for a workspace you administer, every version a release brought: from which server, workspace and version, which version it is here, whether it was adopted or arrived pinned only, and when.
- Same content, no second copy. When this workspace already has a version with exactly the release's content (for example a rule adopted from an independently built environment), the ledger maps to it instead of publishing it again.
- Repeats and retries. A version the ledger already holds is not published again; importing the same release twice changes nothing. A newer release publishes its new versions on top. A source version that comes back with different content is refused (the source changed a published version).
- Conflicts. If this workspace already has a rule or contract with one of the release's keys that the ledger does not own, the review lists it as a conflict and Import stays off. A workspace Admin can Adopt it (typing the key to confirm): its existing versions stay, and releases from that source publish new versions on top. Adopting is recorded in the audit log (
DEPLOYMENT_LEDGER_CHANGED). An asset owned by another source, a business function that differs (it has no versions), and a changed contract (republishing one changes its consumers in place) are not adoptable and travel by governed deployment. - The review shows, for each item, what it becomes here ("version 3 becomes version 2 here", "already imported as version 1", "pinned only").
A release that holds processes is still refused (DEPLOYMENT_RELEASE_NEEDS_GOVERNED_DEPLOYMENT): the platform creates processes only through their lifecycle. Rules other than expression and decision-table rules, decision tables whose pins would need rewriting, and contracts of other kinds are refused the same way. A release that holds legacy forms keeps the earlier package behaviour: every asset is created fresh as version 1, each asset appears once, no content pins a version other than 1, and anything the workspace already has is refused (WORKSPACE_IMPORT_CONFLICTS).
The ledger never trusts the server name a release states: the source is the signer this server trusts. A key rotated over the same pairing link keeps the source; a key trusted from a file is its own source, so after rotating such a key its assets are adopted again. Adopt offers only sources this server trusts.
Release files may be up to about 100 MB; workspace export packages stay limited to 10 MB in Studio. The server refuses a larger upload before reading it.
Production workspaces refuse package imports
A workspace whose environment is Production is a managed target. It refuses every workspace package import, whatever the format (1 to 4), before anything is validated or created (WORKSPACE_IMPORT_MANAGED_TARGET). The refusal is audited (WORKSPACE_IMPORT_REFUSED, with the format), and only after the caller's Admin role is confirmed, so the workspace's tier is never revealed to someone who may not import. Production changes only through a governed deployment (DEP-17a). Development and Staging workspaces keep importing as before.
Workspace targets (DEP-12 part 1)
A target says which workspace on a destination server receives this workspace's releases. There is at most one target per workspace and environment.
- Where: open the workspace, then Deploy → Deployment targets. The table lists each destination environment you may view, whether that server is paired, the workspace key there, and when it was created there.
- Who may see it: a person with a deployment View grant on the environment and at least the Viewer role in the workspace. Environments outside your grants are not listed. Without any of these, the section is not shown and Studio makes no request for it.
- Who may change it: a person with a deployment View grant on the environment and the Admin role in the workspace. API keys cannot change targets.
- Key format: 3 to 64 characters: lower-case letters, digits,
-and_, starting and ending with a letter or digit. Studio shows the rule while you type and waits for a valid key; the server checks it (DEPLOYMENT_TARGET_KEY_INVALID, 422). - Concurrent edits: every change carries the revision it was based on. If someone changed the target in the meantime, the change is refused (
DEPLOYMENT_TARGET_MAPPING_STALE, 409); the dialog then shows the current target, and saving again applies on top of it. - Kept once created: after the workspace has been created on that server (part 2), the target cannot be removed (
DEPLOYMENT_TARGET_MAPPING_IN_USE, 409). - Removing a target clears it and keeps its history; the revision keeps increasing, so a change based on what was read before the removal is refused as stale.
- Permission changes apply at once: if your rights are withdrawn while the page is open, Change and Remove disappear and an open dialog closes.
- Retired environments take no new targets (
DEPLOYMENT_ENVIRONMENT_RETIRED). - Audit: every set, change and removal writes
DEPLOYMENT_TARGET_MAPPING_CHANGEDwith the environment, the old and new key and the new revision. - Storage:
deployment_target_mapping(migration000417). - API:
GET /api/workspaces/{workspaceKey}/deployment/targets,PUT …/targets/{environmentKey}with{targetWorkspaceKey, expectedRevision}, andDELETE …/targets/{environmentKey}?expectedRevision=. The capabilitiesdeployment.targets.viewanddeployment.targets.manageare workspace-scoped.
Setting a target changes nothing on the destination server. Creating the workspace there is the next section.
Creating the workspace on the target (DEP-12 part 2b)
Create there asks a destination server to create this workspace's counterpart under the mapped key, over the signed link between the two servers.
- Before you start (on the destination server): its administrator pairs the servers, then under Deployment → Peer access adds a A new workspace grant for this workspace with the target key, acting as a service account that may create workspaces there (
WORKSPACE_CREATE). - Before you start (on this server): set the target key under Deployment targets, and allow the destination under Release distribution.
- Who may create: a person with deployment View and Deploy grants on the environment and the workspace Admin role, for an active push environment (a pull environment refuses with
DEPLOYMENT_TARGET_CREATE_NOT_PUSH). The release flag must be on, on both servers (DEPLOYMENT_RELEASE_DISABLED). API keys cannot create. - What is checked here first, with nothing sent on a refusal: your authority, the environment, the current pairing (a request prepared before re-pairing is stale), the target and its revision, and the distribution grant (
DEPLOYMENT_DISTRIBUTION_NO_CONSENT). - What is sent: only this workspace's key and name, and the target key. No content, people, roles or members. The other server learns which server asked from the signature, never which person.
- What the other server decides: the reservation for exactly this key and this workspace, its service account, and that account's own permission to create workspaces. It creates the workspace as that service account (who becomes its administrator) and converts the reservation into a One workspace grant, in one transaction. Any refusal there is a plain refusal here (
DEPLOYMENT_PEER_NOT_GRANTED); its reason stays in that server's history. - Waiting for answer: the request is recorded before it is sent. If the other server does not answer, the row shows Waiting for answer and the target can be neither changed nor removed.
- Check again sends the same request again. It is safe: if the other server already created the workspace, it says so and nothing is created twice.
- Stop waiting forgets the request. It needs only the workspace Admin role and deployment View (not the distribution grant or a current pairing). It does not undo anything the other server may already have created; creating again later finds it there.
- Once created: the row shows when it was created, and Change and Remove are gone.
- History: on this server, each step writes
DEPLOYMENT_TARGET_CREATION(requested, refused, withdrawn, created) in the workspace's own history. On the other server, the creation and the conversion are in platform history, with the service account as the creator and this server's name on the conversion. - Storage and API: migration
000422addscreation_requested_atandcreation_link_idtodeployment_target_mapping. The routes arePOST /api/workspaces/{workspaceKey}/deployment/targets/{environmentKey}/createwith{linkId, expectedRevision}andDELETE …/create?linkId=&expectedRevision=. The capability isdeployment.targets.create. The servers talk overPOST /api/deployment/peer/workspaces/create(operationCREATE_WORKSPACE, the target key in the signedX-Inflow-Target-Workspaceheader). - Admission: governed admission (DEP-17a) will also decide this entry point before the release flag is turned on at DEP-P1G.
Release distribution (DEP-12 part 2a)
A distribution grant is this server's consent to send a workspace's releases to one destination server (spec 481 plan S3). The destination's own peer grants decide what it accepts. A distribution grant decides what this server is willing to send.
- Where: open the workspace, then Deploy → Release distribution. The table lists each destination environment you may view that is paired from this server, with which releases may be sent there: all releases, the selected releases, or nothing.
- Choices:
- All releases covers every release of the workspace, including later ones.
- Selected releases covers only the chosen built releases, from 1 to 100.
- Nothing withdraws the grant.
- Who may see it: a person with a deployment View grant on the environment and at least the Viewer role in the workspace. A selected release you cannot open is not shown. In that case you cannot change the grant either, so hidden selections are never dropped by accident.
- Who may change it: a person with deployment View and Admin grants on the environment (Admin also needs the workspace Admin role). API keys cannot change grants.
- Bound to the pairing: a grant belongs to the current link with that server. After re-pairing, the old grant does not apply to the new link, and a change prepared before re-pairing is refused (
DEPLOYMENT_DISTRIBUTION_STALE, 409). Without a trusted link, the change is refused withDEPLOYMENT_DISTRIBUTION_NO_LINK(409). - Releases: only built releases of this workspace can be selected. A retired release is never sent (
DEPLOYMENT_DISTRIBUTION_RELEASE_INVALID, 422). - History: every change writes
DEPLOYMENT_DISTRIBUTION_CHANGEDwith the old and new choice and release numbers. Withdrawing keeps the record, and the revision keeps increasing. - Enforcement: a grant is consent only.
- Creating the workspace on the target (part 2b), and later job claims and release fetches, also re-check the requesting person's or service's current deployment authority.
- Server-wide health and inventory never need a grant.
- Storage and API: the grants are stored in
deployment_distribution_grant(migration000418). The routes areGET,PUT …/{environmentKey}({linkId, audience, releaseIds, expectedRevision}) andDELETE …/{environmentKey}?linkId=&expectedRevision=under/api/workspaces/{workspaceKey}/deployment/distribution-grants. The capabilities aredeployment.distribution.viewanddeployment.distribution.manage.
Outcomes and diagnostics
Deployment refusals and step results are structured outcomes: a stable code plus a few allow-listed parameters. Studio shows approved plain-language text for each code. Raw messages from peers, plugins, databases or migrations are never stored, shown or sent.
Secrets
Releases, logs, audit records and API responses never contain secret values; secrets travel only as vault references. The secret scanner checks content against known secret values and common credential formats, and reports only the kind and position of a match. Audit records redact secret-named fields and any value that looks like a credential.
Canonical feature configuration (spec503)
The server release/capability switches use the canonical file and planned restart. Explicit scope=server native HTTP/MCP writes retain global platform administrator authority; ordinary workspace editing cannot enable a server switch. Infrastructure URLs, trust and exact outbound allowlists retain their existing sources. See Feature switches and migration for exact keys, defaults, scope, direct-edit locking, migration and rollback.