# Source Control

Connect workspace repositories and manage Git review and synchronization

Workspace Source Control connects a SteelEngine workspace to a GitHub repository. Capture every saved workflow and its folder placement, review exact file changes, commit the retained snapshot, and open a pull request into the configured upstream branch from the workspace hub.

Workflow-level Git authoring is paused in code. The former `WORKFLOW_SOURCE_CONTROL_ENABLED` opt-in no longer enables it. Use workspace capture, review, commit, PR creation, and repository settings instead.

Workflow setup, editor Git actions, and legacy editing-branch controls are hidden. Workflow protection, unprotection, resource-assignment, and branch-authoring HTTP mutations return `404 workflow_source_control_disabled`. Existing protection records, read-only guards, approved revisions, and shared workspace synchronization remain intact. Ordinary unprotected workflows retain their normal deployment flow. Capture the workspace explicitly to add its workflows and folder placement to Git.

Organization releases remain a separate self-hosted capability requiring `PROMOTION_ENABLED=true` and valid deployment configuration; hosted installations cannot enable organization promotion.

## How It Works

Workspace review keeps saved drafts separate from a fixed Git snapshot:

1. An organization admin connects an approved GitHub repository.
2. A workspace or organization admin, or a person granted **Manage source control**, chooses the repository, branch, and workspace package. Authoring a new package also sets its managed path.
3. In **Source Control > Changes**, capture every active workflow and its folder placement.
4. Review changes grouped by workflow name, with summaries of step, connection, prompt/code, and resource changes. Expand each workflow to read line diffs of its exact Git files, then commit that snapshot.
5. Open its pull request into the workspace upstream branch, review, and merge in GitHub.
6. Select **Check if merged** to verify the exact merged snapshot.
7. Connect another workspace to the reviewed Git package, on the same branch or a branch receiving a reviewed promotion PR. The workspace may be in another organization or on another installation. Synchronize and deploy according to its policy. Use [Organization Releases](/self-hosting/releases/git-promotion) to coordinate workspaces that do not have independent connections.

**Capture approval and production publication are separate steps.** A capture PR approves the development snapshot. A promotion PR into a connected production workspace's branch triggers synchronization; its deployment policy determines whether publication is automatic. Organization Releases use their own preparation and activation flow.

See [Workspace Source Control](/source-control/workspace-hub) for the complete procedure and limits. The retained [legacy workflow guide](/source-control/protect-and-branch) documents existing protection records; its authoring controls are unavailable.

For a new repository and two environments, start with the [Dev, QA, and Prod walkthrough](/source-control/production-workspaces#start-with-a-new-repository-and-dev-qa-and-prod). It explains creating Prod first, selecting a package by its name from Git, and synchronizing before deployment.

## What Git Stores

SteelEngine writes a deterministic, reviewable bundle under the workspace's managed repository path. Workflow IDs provide stable identity, so renaming a workflow changes its metadata instead of moving its directory.

| Stored in Git                                                                                          | Kept in SteelEngine                        |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| Workflow name, description, color, execution timeout, graph, layout, variables, and interface metadata | Secret values and provider tokens          |
| Block configuration, prompts, and code in sanitized files                                              | Credential and resource assignment targets |
| Logical resource requirements, such as a required connection role                                      | Autosaved branch working copies            |
| Stable workflow and block IDs                                                                          | Deployment versions and runtime history    |

The managed workflow directory has this shape:

```text
<managed-path>/workspace-snapshot/workflows/<workflow-id>/
  metadata.json
  workflow.json
  layout.json
  bindings.json
  nodes/
```

`layout.json` holds canvas layout: block positions and any wire ties. `workflow.json` holds the graph itself, so moving a block or a tie changes only `layout.json`.

The sibling `workspace.json` manifest records all workflows and their folder hierarchy. SteelEngine owns the `workspace-snapshot/` directory. Files outside the managed workflow paths are preserved, so the repository can also contain code owners, documentation, and other workspace paths.

## Current Scope

[Branch-connected workspaces](/source-control/production-workspaces) follow a repository, branch, and workspace package across organizations and installations. Each destination authorizes its own repository access and uses its own local resources. The branch lock, direct or Git-only workflow editing, and manual or automatic deployment are independent settings. Signed push hooks, manual synchronization, and hourly reconciliation let the Worker verify approved snapshots and preserve stable destination IDs. Deployments activate workflows sequentially and attempt to restore prior versions on failure.

Enabled self-hosted installations can follow an organization repository and branch through [Organization Releases](/self-hosting/releases/git-promotion). The target verifies Git approval and can deploy the managed workspaces together manually or automatically. Workspaces with their own Source Control connection are excluded from organization capture, deployment, and rollback.

* GitHub is the supported provider.
* Each workspace has one active repository binding.
* One authoring workspace owns a repository/branch/package-path combination. Multiple destination workspaces may follow that same package and branch.
* Create and save workflows in SteelEngine before capturing the workspace. Capture does not protect individual workflows.
* Workspace snapshots include workflow folder placement. Existing workflow protections continue to enforce their folder movement guards.

## Get Started

[Workspace Source Control](/source-control/workspace-hub)

Follow setup through PR review and deployment using the status strip and the Changes, Releases, and Settings tabs.

[Connect GitHub](/source-control/setup)

Enable the organization integration, connect a repository, and bind a workspace path.

[Branch-connected workspaces](/source-control/production-workspaces)

Configure a repository package, branch lock, editing policy, and deployment policy across environments.

[Troubleshoot](/source-control/troubleshooting)

Recover from connection, synchronization, validation, and resource-assignment issues.

## Common Questions

**Does Source Control require a repository?**

Yes. Workspace snapshots are committed and reviewed in the connected GitHub repository. Without a connection, ordinary draft and deployment history remain available.

**Does removing a repository connection delete the GitHub repository?**

No. Organization settings managers can remove an unused connection from SteelEngine while retaining its history. Workspaces still using it must change connections first; deleted workspaces do not block removal. The GitHub repository, branches, and pull requests remain.

**Does merging a pull request deploy the workflow?**

A capture PR approves the development snapshot. Merging a promotion PR into a connected production workspace's branch synchronizes it, and publishes it when automatic deployment is enabled. Otherwise select Deploy synced version. Organization Releases have their own deployment steps.

**Are secrets committed to Git?**

Credential fields are removed before commit, and Git keeps only logical resource requirements. Free text such as prompts and code is committed as written. Review warns when a captured file holds a credential-shaped value; it does not block the commit.

**Can I review every workflow at once?**

Yes. Capture workspace includes every active workflow and its folder placement in one review and PR, without enabling individual workflow protections.

**Do the source and destination need to be in the same organization?**

No. Git carries the package and its source identity. Each destination needs its own authorized repository connection, local resource assignments, and running Worker. It does not need access to the source workspace's database.

**How do I change a saved workspace branch?**

Use the Workspace branch selector at the top, then confirm the connection change. Change connection edits the repository and workflow direction. Promote to branch opens a PR to the next environment without reconnecting this workspace. Workflow editing and deployment stay separate.
