# Git Approval and Release Status

Configure one organization repository, review every workspace, and explicitly activate an approved release

Use **Organization settings → Organization releases** on an enabled self-hosted installation. One promotion PR contains a fixed inventory of every workspace. Merging approves that content. The target independently checks, prepares, and deploys it.

This implementation promotes supported workflow definitions across every workspace. Apps, table definitions, knowledge bases, and workspace documents currently block organization capture; they are never silently omitted. Integration credentials, runtime data, Kubernetes rollout, traffic switching, and trigger ownership remain separate. This is not acceptance of the complete blue/green architecture.

Workflow-level Git setup, editing branches, and editor controls are paused in code. The former environment opt-in cannot restore them. Workspace capture, review, commit, PR creation, repository settings, and synchronization remain available. Existing workflow protections and approved snapshots are retained. Organization releases still include every workspace, including those with their own Git bindings.

## Set Up the Authoring Installation

Organization admins can configure the repository and upstream branches by default. To delegate this to a custom role, grant **`organization:promotion_repository_configure`** for the organization and read access to every workspace. Workspace admin access, Supervisor, or Member roles alone do not grant this authority. This permission is separate from promotion policy and signing-trust administration. Users without it see the existing repository and branches as read-only, and direct API changes are rejected. Every save rechecks current access, including API-key scope restrictions and revoked role grants.

1. Complete [Kubernetes setup](/self-hosting/releases/kubernetes-setup), including a stable installation identity, enabled promotion, environment policy, and signing key. The existing CLI/API configures installation policy and trust.
2. Connect GitHub in Integrations. Select an account and repository accessible to the installed GitHub App, or create a private repository. Grant access only to the intended repository.
3. Open **Organization settings → Organization releases** and select **Authoring**.
4. Select the organization repository, development branch (default `dev`), promotion target branch (default `prod`), target environment key, and repository folder (default `steelengine`). The target branch does not fall back to the repository default.
5. If needed, enable **Create missing development and target branches** and select the existing starting branch. Setup preserves branches that already exist. An empty repository needs an initial commit.
6. Save. Existing workspace Git bindings are preserved and shown as exceptions. Unbound workspaces receive the shared repository, development branch, and a stable `steelengine/workspaces/<workspace-id>` folder.

Workspace names remain visible in the manifest and UI. Folder identities stay stable when a workspace is renamed. A release writes its signed component packages below each workspace folder's `release/` directory; `steelengine/organization-release.json` signs the complete inventory, target, and component hashes.

## Capture and Review

1. Make changes in development. If the workspace uses captures, capture all workflows in **Workspace Source Control > Changes**, review and commit the snapshot, then merge its PR into the workspace upstream branch. Organization capture verifies that this exact snapshot matches the current workflows and folders; later edits require another workspace review. The release records that workspace commit as workflow provenance. For existing protected workflows, merge the workflow review PR and synchronize its approved version first. Unmerged branch edits are not included. Workspaces without workspace captures continue to freeze ordinary workflow definitions in the organization capture for review in the organization PR.
2. Select **Create organization release**. The page lists unsupported content by workspace before capture. Capture rechecks access and supported content inside the transaction. A failure rolls back the complete capture rather than producing a partial organization.
3. Select **Open promotion PR**. Review all workspace files and retirements against the configured target branch. Continued edits in development require another candidate; retries reuse the retained candidate bytes.
4. Merge through your GitHub branch rules. Select **Check PR approval** on the authoring installation, or **Find approved release** on the target.

Approval verification checks the immutable repository ID, configured target branch, PR head, merge commit, ancestry, complete file inventory, and exact retained content. A modified candidate or a newer release on the branch requires fresh verification. A source installation does not infer whether a remote installation is deployed.

## Set Up the Target Installation

The target needs its own GitHub connection and target-local integrations. Use the same repository, root, and branch mapping. On the authoring installation, expand **Source IDs for target setup** on a captured release; select an ID field to copy its full value. On the target, select **Target**, enter the source deployment and organization identities, and map every source workspace ID to an empty target workspace.

The configured target environment key must match the target installation's environment key. The mapping must cover every local workspace exactly once. Existing source-to-target mappings cannot be reassigned; add new mappings when introducing additional workspaces. Configuration changes invalidate pending readiness plans.

Install independently authorized public trust covering the producer signing key for **each source workspace**. Do not copy the development private key. Configure the target's allowed Git carrier with `refKind: branch` and the exact promotion branch. Existing signed-review and validation requirements still apply: Git merge approval does not silently replace them. If your reviewed policy intentionally uses GitHub as the only review gate, configure that explicitly rather than relying on a default.

## Check, Prepare, Deploy

1. **Find approved release** imports the approval record after authoritative Git and signature verification. It does not change definitions or runtime pointers.
2. **Check readiness** imports the signed component packages and generates an apply plan for every workspace. Fix missing trust, permissions, integration assignments, unsupported tools, or incompatible definitions. Review the planned changes grouped by workspace and workflow name. Summaries compare the captured files with the currently deployed release; readiness also checks target-local drift. Expand **Technical details** for object and change IDs. Review all changes requiring acceptance.
3. **Prepare release** applies all supported workspace definitions in one transaction and creates activation preflights. Accept exactly the reported changes requiring approval across the organization, including any target drift you intend to replace. Each workspace receives only its own acceptances; missing, duplicate, or unrelated change IDs are rejected. Existing active workflow versions continue to serve. Preparation failures roll back all workspace definition changes.
4. **Deploy organization** shows an explicit confirmation naming the target environment and workspace count. Deployment rechecks Git, trust, access, configuration, inventory, resources, and plan freshness. One database transaction commits every workspace activation and the organization generation. A failure leaves the prior active pointers unchanged.
5. Verify the target's **Currently deployed** release and generation. New runs use the activated versions; existing runs retain their pinned versions. Separately verify infrastructure health and traffic routing.

This local rehearsal promotes an approved workspace snapshot through an organization PR into `prod`. Generation 3 remains live through preparation; explicit deployment activates generation 4 across all three workspaces.

![Find the approved organization release on prod, check readiness, prepare it while generation 3 stays live, then confirm deployment of generation 4](https://docs.steelengine.com/static/source-control/organization-dev-to-prod.gif)

[Open the complete MP4 walkthrough](/source-control/workspace-release-walkthrough.mp4) for the preceding workspace capture, review, commit, and PR steps. The walkthrough is assembled from captured local browser steps; GitHub review and merge occur between them. The numbered instructions above provide the same procedure without animation.

Acceptance applies to the exact readiness plan shown. If a new check produces a different plan, review and accept its changes again.

Readiness plans expire. Run **Check readiness** again and prepare the renewed plan before deployment. A lost response can be retried; an already committed deployment returns its existing generation. Direct workspace activation/rollback cannot bypass an organization-managed target's deployment boundary.

## Restore a Previous Organization Release

1. On the target, expand **Earlier releases** and select **Check rollback readiness** on a previously deployed release.
2. Review the complete organization rollback plan. The server checks the retained activation proof, current access, trust, retention window, runtime compatibility, and target-local resource assignments for every workspace. A missing or incompatible resource blocks the whole rollback.
3. Accept the exact reviewed plan, including any workflows that will stop accepting new runs, then select **Restore N workspaces**.
4. Verify **Currently deployed**. Rollback creates a new generation that restores the retained workflow versions and assignments across all workspaces in one transaction. Current drafts, local resource values, runtime data, and in-flight runs are preserved.

A failed transaction preserves every active pointer. Refresh status after a lost response; retrying the same rollback plan returns its committed generation without activating again. A stale or expired plan requires **Check rollback readiness again**. Git availability is not required to replay a committed rollback or restore an eligible retained activation; the original Git carrier must still satisfy target policy.

Rollback requires the same complete workspace inventory, mappings, and repository configuration as the retained release. Removing a whole workspace or changing those mappings is not a supported retirement operation. A workflow removed within an existing workspace can be retired through a new reviewed release.

## Read the Status Correctly

The page separates **Currently deployed** from **Git approved**. The target shows the live generation and activation time, then **Next release** with the next preparation or deployment action. The authoring installation shows **Latest release** and its Git review progress. **Earlier releases** expands retained candidates and previous deployments; their actions remain available. Expired readiness warnings apply to pending deployments, not already deployed releases.

The workspace list links directly to workflow review and shows each upstream branch and repository source. Expand a mapping to inspect its managed folder. **Repository settings → Back to releases** leaves configuration without saving.

| UI fact                       | Evidence                                                                    | What it does not mean                                                 |
| ----------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Awaiting PR merge             | A promotion PR exists                                                       | Approved or deployed                                                  |
| Git approved                  | Exact candidate verified in a merged PR on the configured branch            | Target definitions prepared or runtime active                         |
| Prepared · checks required    | Definitions prepared; activation checks need attention                      | Safe to activate immediately                                          |
| Ready to deploy · not live    | Current stored preflights passed and have not expired                       | Deployed                                                              |
| Currently deployed            | Target's active organization pointer references this release and generation | Kubernetes traffic switched or external trigger ownership transferred |
| Previously deployed           | Retained historical activation                                              | Still serving new runs                                                |
| Deployment reported on target | This is the authoring installation                                          | Remote deployment success or failure                                  |

## Refresh and Webhooks

Organization approval currently uses explicit **Check PR approval** / **Find approved release** actions. **Refresh status** reloads recorded state; it does not fetch a new Git approval. Workflow Source Control's signed webhook handler continues to synchronize workflow Git changes. Automatic organization webhook reconciliation and remote deployment receipts are not implemented in this increment. No webhook activates an organization release.

## Current Boundaries

The organization coordinator has a configured target per installation and captures at most 200 workspaces, a 64 MiB aggregate, and bounded component files. The signed file CLI remains workspace-scoped. Workspace removal/retirement, additional object adapters, cross-workspace workflow references, and automatic blue/green traffic/trigger coordination remain separate work. Rehearse supported workloads and failure recovery before client production acceptance.