# Organization Releases

Plan organization-wide promotion across self-hosted SteelEngine environments

Organization releases provide a guarded workflow-definition path to promote every workspace in a self-hosted SteelEngine organization together. Builders work in development; reviewers approve a fixed release; production supplies its own connections and data.

**Implementation and architecture guide, updated October 21, 2026.** The organization release UI and Git promotion coordinator now capture all workspaces, verify a merged promotion PR, prepare definitions, and atomically activate supported workflows. The feature is self-hosted and disabled by default. Other object adapters and complete blue/green infrastructure/trigger coordination remain planned. See [Git Approval and Release Status](/self-hosting/releases/git-promotion) for the implemented scope; the [Current CLI Rehearsal](/self-hosting/releases/current-cli) remains workspace-scoped. This guide is not full production acceptance.

## Read This Guide by Role

| Reader                        | Start here                                                    | Outcome                                                         |
| ----------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| Sponsor or solution architect | This page and [Blue/Green](/self-hosting/releases/blue-green) | Agree scope, ownership, and rollout boundaries                  |
| Kubernetes operator           | [Kubernetes Setup](/self-hosting/releases/kubernetes-setup)   | Prepare isolated environments and a verified Helm configuration |
| Integration administrator     | [Integration Bindings](/self-hosting/releases/integrations)   | Connect production accounts once and map required resources     |
| Builder or reviewer           | [Git Promotion](/self-hosting/releases/git-promotion)         | Understand what a PR approves and what makes a release live     |
| On-call engineer              | [Operations](/self-hosting/releases/operations)               | Prepare monitoring, rollback, and incident procedures           |

## Availability

Availability refers to the reviewed repository version, not a guarantee about a published image or CLI package. Record the actual build installed during your pilot.

| Capability                                                        | Reviewed status                                                                                                  |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Whole-workspace capture, review, commit and PR                    | Implemented for active workflows and folder placement; works with workflow controls disabled                     |
| Individual workflow review through GitHub                         | Paused in code; no environment opt-in. Existing protection and synchronization remain enforced                   |
| Signed file transfer, preflight, apply, activation, rollback      | Implemented self-hosted API/CLI for the reviewed workflow profile; requires configuration and compatible workers |
| Credentials and provider settings assigned on the target          | Implemented for supported workflow resources                                                                     |
| One release covering every workspace                              | Implemented for supported workflows and folders; unsupported content blocks capture                              |
| Organization release PR and target verification                   | Implemented with explicit refresh, preparation and atomic activation; automatic reconciliation remains planned   |
| Apps, table schemas, knowledge-base configuration, workspace docs | Target scope; adapters and end-to-end support are incomplete                                                     |
| Coordinated production blue/green cutover                         | Planned; the current Helm chart does not implement this protocol                                                 |
| SteelEngine container or database upgrade                         | Customer-operated infrastructure change; separate from content promotion                                         |

## The Organization Is the Release Boundary

Organization and workspace source control remain available at their existing boundaries. Workflow-specific authoring is paused:

| Scope             | What you control                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization      | GitHub setup, release configuration, every workspace's supported content, promotion PRs and atomic activation; organization rollback remains planned          |
| Workspace         | Repository, path and target-branch settings; capture all workflows, review exact files, commit and open a PR; synchronization and workflow deployment history |
| Workflow (legacy) | Retained protections and approved revisions; individual authoring controls are unavailable                                                                    |

Organization releases require `PROMOTION_ENABLED=true` and valid self-hosted configuration. Pausing workflow authoring does not change which workspaces are included in organization releases.

Use the [Workspace Source Control](/source-control/workspace-hub) hub for a team's Git work. Keep its repository and branch settings, PRs and deployment history when adopting organization releases. Organization onboarding should discover these existing bindings, including workspaces that use different repositories. The organization promotion repository and environment mapping are configured separately from workspace authoring targets.

On an organization-managed production target, activation still coordinates every workspace. A workspace review PR approves its changes; merging it does not independently activate that workspace in production. The workspace **Releases** view shows individual workflow deployment versions and does not represent an atomic organization release.

Once a workspace uses captures, organization capture requires a merged workspace snapshot matching its current workflows and folders. Later edits require another workspace review. The organization release records the workspace commit as provenance.

A protected workflow's approved snapshot can be included in an organization release. An unmerged workflow PR remains separate from that candidate. On a promotion-managed target, an individual workflow deployment must not bypass the organization release boundary.

A release must account for every source workspace. Unchanged workspaces remain in the inventory with their exact retained version. New workspaces appear as additions; removed workspaces require an explicit retirement decision. An unavailable or unsupported workspace blocks capture instead of disappearing from the release.

Workspace names are labels. Stable logical identities link source workspaces and objects to their target equivalents, even when local database IDs or names differ. An existing production workspace must be deliberately adopted through a supported mapping procedure; a matching name is insufficient.

“Entire organization” means the supported, declarative product definitions across all its workspaces. It does not mean copying the development database or granting development users access to production.

| Included in the target release model                   | Remains local to each environment                                                   |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Workspace inventory and supported descriptive settings | Organization memberships, access grants, SSO, billing, license, deployment identity |
| Workflow graphs, prompts, code, and supported metadata | Running executions, history, runtime counters, personal drafts                      |
| App layouts and supported application configuration    | Sessions, visitor data, live application records                                    |
| Table schemas and supported constraints                | Production rows, business data, database credentials                                |
| Knowledge-base configuration and source requirements   | Documents, embeddings, connector credentials, ingestion state                       |
| Supported workspace doc content                        | Private storage locations and environment-specific resource assignments             |
| Logical connection roles and dependency requirements   | OAuth grants, API keys, provider apps, secrets, account/channel/resource IDs        |

Supported configuration is an explicit allowlist. A URL or identifier is not automatically portable because it is non-secret. Production endpoints, Slack channels, provider tenants, and similar destinations need target-local bindings or a reviewed environment overlay.

## One Candidate, Several Environments

The intended lifecycle is: edit in development, capture a complete organization candidate, open a promotion PR, validate the exact candidate, merge, prepare the target, then activate according to target policy. Staging and production use the same payload digest. Validation evidence is added without rebuilding the content from whatever development contains later.

Git stores reviewable definitions and requirements. An immutable digest identifies the release content. The target separately records the PR/commit that approved it, local binding revisions, the active generation, and the infrastructure build that ran it.

## Responsibilities

| Owner                               | Responsibilities                                                                                                                                           |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SteelEngine                         | Serialize supported definitions; validate identity, trust, dependencies and assignments; retain audit evidence; coordinate content activation and rollback |
| Customer platform team              | Kubernetes, Helm, TLS, ingress, storage, Temporal, container rollout, backups, monitoring and recovery                                                     |
| Customer organization administrator | Source/target mapping, repository access, target connections, review policy and release authority                                                          |
| Builders and reviewers              | Author changes, review impact, execute agreed validation and approve the exact release                                                                     |

The customer pipeline may orchestrate a container upgrade and an organization release together. It must still record separate results and recovery points for each. A successful Helm rollout is not proof that every workspace was promoted, and a successful content activation is not proof that traffic moved to green.

## Before Agreeing a Production Date

Agree the complete workspace inventory, supported object kinds and tools, integration owners, data compatibility rules, and recovery objectives. Rehearse in isolated installations using the exact intended builds. Obtain evidence for organization-wide atomic activation and trigger ownership before describing the planned workflow as production-ready.