Git sync docs rework (#1193)

* Workspace forks (merge ui + cahngelog)

* Update git sync docs

Less emphasis on promotion, add the setup (including CI/CD) as part of
this page

* Remove promotion details from git sync docs

* Centralize promotion workflow instructions, recommend workspace forks

* Update local development

* Add tags to changelog

* Rename to Git promotion

* New infographic for forks

* fixes

* fixes

---------

Co-authored-by: Henri Courdent <122811744+hcourdent@users.noreply.github.com>

Author: wendrul

changelog/2025-12-16-workspace-forks/index.md

@@ -0,0 +1,17 @@
+---
+slug: workspace-forks
+version: v1.593.0
+title: Workspace forks
+tags: ['Workspaces', 'Git sync', 'Collaboration']
+description: Create independent copies of workspaces for parallel development workflows, similar to git branches. Merge changes back to parent workspaces directly from the UI or through git sync.
+features:
+  [
+    'Fork workspaces to create independent development environments',
+    'Automatically create git branches when used with git sync',
+    'Merge forked workspaces back to parent workspaces from the UI',
+    'Multiple developers can work on separate forks simultaneously',
+    'Deploy individual items to parent workspace using deployment UI'
+  ]
+docs: /docs/advanced/workspace_forks
+video: /videos/merge-ui-demo.mp4
+---

docs/advanced/11_git_sync/index.mdx

@@ -2,37 +2,34 @@ import DocCard from '@site/src/components/DocCard';
 
 # Deploy to prod
 
-To deploy to prod, 3 options are possible.
-
-[Draft and deploy](#option-1-draft-and-deploy---single-workspace) is the simplest method. It is meant to be used in a single workspace.
-
-[Git integration](#option-2-deploy-to-prod-using-a-git-workflow---multi-workspace-recommended) is clearly the superior, most powerful method but it is more complex. Usually, to deploy to prod you would want absolutely to have the normal CI flow that goes through one review which is something that is built-in with GitHub/GitLab. Also you may want to put some CI checks there.
-
-However, in a setting where you have dev/staging/prod, you could use the [UI to deploy to staging from dev](#option-3-deploy-to-prod-using-the-ui-only---multi-workspace), and then use git between staging and prod to tighten down prod.
+When working on Windmill, you will quickly be looking for ways to iterate on and test your scripts, flows, and apps all the while having a working version running. The following section explains the different methods available in Windmill to have a production environement and deploy to it.
 
 ## Option 1. Draft and deploy - Single workspace
 
 A simple setup in which deploying to prod means deploying items that have been iterated on in the UI as Drafts.
 Deployments in Windmill are commonly done from the same workspace using the [Draft and deploy](../../core_concepts/0_draft_and_deploy/index.mdx) buttons.
 
-## Option 2. Deploy to prod using a git workflow - Multi workspace (recommended)
+## Option 2. Workspace forks - Multi workspace (recommended)
+
+[Windmill workspaces](../20_workspace_forks/index.mdx) can be forked, creating a new copy of the workspace at that point in time. The forked workspace can be iterated on, tested, and once changes are ready, merged back to the original workspace, thus deploying the new versions of the scripts, flows, or apps. The workflow will be familiar to anyone who has used branches in version control tools such as git. The analogy can be further reinforced if [Git Sync](../11_git_sync/index.mdx) is setup: Windmill will autmatically create branches for each of the forks, and merging can be controlled direclty through git.
+
+## Option 3. Git Promotion workflow: deploying through git - Multi workspace (possible cross-instance)
 
-The integration can be used to push from git, and receive changes done from the UI in a bi-directional way.
-You can also use a separate dev and staging branch and repo and have Windmill create automatically branches and Pull Request upon any changes deployed to staging/dev.
+This is a more complex but very reliable setup that leverages [Git Sync](../11_git_sync/index.mdx) to deploy from one workspace to another through git. When changes are done to the Staging workspace, they are pushed to a branch in the Prod repo. Once merge to the main branch of the Prod repo, the Prod workspace is updated with the changes.
 
-This process can be used in particular for [local development](../4_local_development/index.mdx) with a solid setup:
+This workflow lets you review all the changes on a PR before merging and deploying. It also has the advantage, unlike the other options here, to work across separate windmill instances.
 
-![Local development Setup](../4_local_development/local_development.png 'Local development Setup')
+![Git Promotion](/images/git_promotion.png 'Git Promotion')
 
 <div className="grid grid-cols-2 gap-6 mb-4">
 	<DocCard
-		title="Deploy to prod using a git workflow"
+		title="Deploy to prod using the Git Promotion workflow"
 		description="Windmill integration with Git repositories makes it possible to adopt a robust development process for your Windmill scripts, flows and apps."
 		href="/docs/advanced/deploy_gh_gl"
 	/>
 </div>
 
-## Option 3. Deploy to prod using the UI only - Multi workspace
+## Option 4. Deploy to prod using the UI only - Multi workspace
 
 From a workspace in Windmill, you can deploy a script/flow/resource/variable and all its dependencies to another workspace.
 

docs/advanced/12_deploy_to_prod/index.mdx

@@ -8,7 +8,7 @@ Manage changes to scripts workflows, apps and resources using commits & push on
 
 From the workspace settings, you can set a [git_repository](../../integrations/git_repository.mdx) resource on which the workspace will automatically commit and push scripts, flows and apps to the repository on each [deploy](../../core_concepts/0_draft_and_deploy/index.mdx).
 
-This video shows how to set up a Git repository for a workspace (Git sync - sync mode).
+This video shows how to set up a Git repository for a workspace (Git Sync).
 
 <iframe
 	style={{ aspectRatio: '16/9' }}
@@ -19,7 +19,6 @@ This video shows how to set up a Git repository for a workspace (Git sync - sync
 	allowFullScreen
 	className="border-2 rounded-lg object-cover w-full dark:border-gray-800"
 ></iframe>
-
 <br />
 
 Git sync is [Cloud plans and Self-Hosted Enterprise Edition](/pricing) only.

docs/advanced/13_version_control/index.mdx

@@ -20,7 +20,7 @@ Key features:
 - **Git integration**: Automatically creates corresponding git branches using the git sync workflow
 - **Team collaboration**: Multiple developers can work on separate forks simultaneously
 
-<!-- TODO: Add diagram showing fork relationship and git branch mapping -->
+![Workspace Forks and Git Sync](/images/workspace_forks.png)
 
 ## Example feature development workflow
 
@@ -35,8 +35,8 @@ Key features:
 ### Prerequisites
 
 - Being on a self-hosted EE instance
-- [Git sync](../11_git_sync/index.mdx) configured (recommended for full functionality)
-- [CI/CD actions ](../9_deploy_gh_gl/index.mdx#github-actions-setup) to merge back from the git remote to Windmill
+- [Git sync](../11_git_sync/index.mdx) configured (optional, required only for git-based workflows)
+- [CI/CD actions ](../9_deploy_gh_gl/index.mdx#github-actions-setup) to merge back from the git remote to Windmill (only required for git sync workflows)
 
 ### Fork creation
 
@@ -80,7 +80,7 @@ When workspace forks are used with [git sync](../11_git_sync/index.mdx), Windmil
 the parent workspace, and keep track of changes there. External changes to the branch are then synced back to the forked workspace if the appropriate
 CI/CD actions are setup. Once the changes are ready, a PR can be opened to sync back changes to the original workspace.
 
-Workspace forks are designed to be used with git sync, so make sure to have it properly setup and in particular the [CI/CD actions](../9_deploy_gh_gl/index.mdx#github-actions-setup) specific to forks should be set. Make sure to not forget the `push-on-merge-to-forks.yaml` action.
+Workspace forks can be used with git sync for full version control integration. If using git sync, make sure to have it properly setup and in particular the [CI/CD actions](../9_deploy_gh_gl/index.mdx#github-actions-setup) specific to forks should be set. Make sure to not forget the `push-on-merge-to-forks.yaml` action.
 
 ### Fork and branch naming
 
@@ -101,7 +101,28 @@ This naming convention is what enables Windmill to match branches to workspaces
 
 Once a fork is created, it is automatically setup to deploy to its parent branch. You can deploy any item to the parent branch directly from the UI by clicking it and selecting `Deploy to staging/prod`. Learn more about the [Deployment UI](../../core_concepts/12_staging_prod/index.md).
 
-There is currently no way to update the parent workspace changes back to the fork through the UI, but some features are planned to remediate to this.
+### Merge workspaces from the UI
+
+You can merge changes from a forked workspace back to its parent workspace directly from the UI without requiring git sync. This provides a simpler workflow for teams that don't need full git integration.
+
+To merge a fork:
+
+1. Navigate to the forked workspace
+2. On the home page, a banner will show you the diff with its parent workspace. Click `Review & Deploy Changes`
+3. Review the changes and confirm the merge
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	autoPlay
+	loop
+	src="/videos/merge-ui-demo.mp4"
+/>
+
+#### Items behind and conflicts
+
+If it is detected that some of the differences come in fact from the original workspace, these changes will be shown as 'behind'. Before deploying, all behind changes must be updated into the fork and properly tested. When an items has changes that are both ahead and behind, it will be marked as a conflict and will be warned to the user. The user must then review the diff and decide how to edit the item to resolve the conflicting changes. Until deployed or updated however, the item will still be marked as a conflict. For more granular conflict detection and better tracked resolution, you can choose to merge the workspaces through a git workflow instead.
+
+The merge will transfer all selected scripts, flows, apps, resources, and variables from the fork to the parent workspace.
 
 ### Git sync based merging
 
@@ -134,7 +155,3 @@ When git sync is properly setup, the workspace is synchronized with one of the b
 		href="/docs/core_concepts/collaboration"
 	/>
 </div>
-
-<!-- TODO: Add troubleshooting section -->
-<!-- TODO: Add FAQ section -->
-<!-- TODO: Add API reference for programmatic fork management -->

docs/advanced/20_workspace_forks/index.mdx

@@ -140,7 +140,7 @@ wmill gitsync-settings pull --promotion main
 wmill gitsync-settings push --promotion production
 ```
 
-When using the `--promotion` flag, the command will use `promotionOverrides` instead of regular `overrides` from the specified branch in your `wmill.yaml`. This should be used when your git sync connection is configured in [promotion mode](../11_git_sync/index.mdx#promotion-mode).
+When using the `--promotion` flag, the command will use `promotionOverrides` instead of regular `overrides` from the specified branch in your `wmill.yaml`. This should be used for [Git Promotion](../9_deploy_gh_gl/index.mdx) connections.
 
 ## Differences from sync command
 
@@ -154,4 +154,4 @@ The `gitsync-settings` command is specifically for managing configuration, not w
 | **File Operations** | Modifies `wmill.yaml` structure | Creates/updates resource files in sync directory |
 | **Safety** | Configuration changes only | Can create/delete workspace resources |
 
-For more details on the `wmill.yaml` configuration structure, see [wmill.yaml](./sync.mdx#wmillyaml).
+For more details on the `wmill.yaml` configuration structure, see [wmill.yaml](./sync.mdx#wmillyaml).

docs/advanced/3_cli/gitsync-settings.mdx

@@ -10,48 +10,25 @@ Windmill has [its own integrated development environment](../../code_editor/inde
 
 To simply create and edit scripts and flows locally, you can directly go to the [Develop Locally](#develop-locally) section.
 
-For a more complex setup involving Git, you can go to the [Local development Recommended Setup](#local-development-recommended-setup).
-
-<iframe
-	style={{ aspectRatio: '16/9' }}
-	src="https://www.youtube.com/embed/sxNW_6J4RG8"
-	title="Local development quickstart"
-	frameBorder="0"
-	allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-	allowFullScreen
-	className="border-2 rounded-lg object-cover w-full dark:border-gray-800"
-></iframe>
-
-## Local development recommended setup
-
-Local development involves two components:
-
-1. Being able to create and edit Windmill scripts and flow from your favorite IDE.
-2. Deploy them to Windmill and at the same time [version](../13_version_control/index.mdx) them in a Git repository.
-
-In addition to the core functionalities just mentioned, some might want to add the concept of [deployment](../12_deploy_to_prod/index.mdx). This encompasses having a staging and production Windmill environment, and being able to deploy from Staging to Production.
-
-The diagram below illustrates the full process. We're going to explain it quickly, and in the following sections we will decompose it.
-
-![Local development](./local_development.png)
-
-It works as follows:
-
-- 2 different workspaces exist in Windmill: one for Staging and one for Prod, and a Git repository that has been set to sync the Windmill Staging workspace.
-- Some developers work from their favorite IDE. They can create new Windmill scripts and flows, edit existing ones, and push them to the Staging repository. Some developers can work directly in Windmill's web IDE. All of this happens in the Staging workspace.
-- Every time a script or a flow is deployed in the Staging workspace, Windmill will automatically commit the change to the Git repository using [Git sync](../11_git_sync/index.mdx). It can either commit directly to a specific (i.e. `staging`) branch, or open PRs to this branch (one PR per script/flow).
-- Within the Git repository, every time the `staging` branch is merged into the production branch (i.e. `main`), all the changes are pushed at once the Windmill Production workspace.
-
-To summarize, developers operate only in Windmill Staging workspace. Windmill Production workspace is updated only by the CI when the Git staging branch is merged into the production branch.
-
-Now let's deep dive into the first part. We will first explain how developers can set up their local environment to be able to create and edit Windmill script from their IDE, then we will see how to sync Windmill workspaces to a Git repository.
-
-The second part is well covered in:
+Usually however, you will need for a robust setup to enable collaboration and compatibility with version control tools like git. The recommended approach for this is to use [Workspace Forks](../20_workspace_forks/index.mdx) and [Git Sync](../11_git_sync/index.mdx).
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Workspace forks"
+		description="Create workspace forks for parallel development workflows"
+		href="/docs/advanced/workspace_forks"
+	/>
+	<DocCard
+		title="Git sync"
+		description="Automatically commit and push workspace changes to your Git repository."
+		href="/docs/advanced/git_sync"
+	/>
+</div>
 
+Another advanced workflow that doesn't use workspace forks is explained here:
 <div className="grid grid-cols-2 gap-6 mb-4">
 	<DocCard
-		title="Deploy to prod using a git workflow"
-		description="Windmill integration with Git repositories makes it possible to adopt a robust development process for your Windmill scripts, flows and apps."
+		title="Git Promotion workflow"
+		description="Windmill integration with Git makes it possible to have a robust git-based deployment workflow"
 		href="/docs/advanced/deploy_gh_gl"
 	/>
 </div>