Git sync docs rework

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/windmill_collaboration.mdx

@@ -0,0 +1,51 @@
+import DocCard from '@site/src/components/DocCard';
+
+# Collaborating on Windmill
+
+In windmill there are multiple ways to collaborate
+
+## Workspace forks
+
+The easiest and main way of collaborating on windmill is through the use of workspace forks. This feature lets users branch off of a workspace and have an exact copy where they can create new items or make changes, test them, and deploy them to the main workspace once it's all working.
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	autoPlay
+	loop
+	src="/videos/merge-ui-demo.mp4"
+/>
+
+
+## Git sync
+
+Git sync is a feature that replicates the state of a workspace into a git repository. When properly set-up, changes made to the repository are immediately reflected in the workspace, and vice-versa. This enables local development as well as development in the Web IDE to be tracked and managed by git, and any git-based workflow is possible.
+
+
+### Git sync + Workspace forks
+
+Workspace forks unlock their full potential when git sync is enabled. When a fork is created, a branch with a corresponding name is created, and changes are tracked there.
+
+### Example: feature development workflow
+
+1. **Create fork**: The user forks the `main` workspace into a fork named `wm-fork-new-feature`
+2. **Develop**: User makes changes in the forked workspace -> The changes are reflected in the branch `wm-fork/main/new-feature` of the repo
+3. **Create PR**: A PR is automatically created by the CI from `wm-fork/main/new-feature` -> `main`
+4. **Review & merge**: Team reviews changes before merging to main branch
+5. **Sync back changes**: Changes are automatically synced to the main workspace as soon as the PR is merged.
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	autoPlay
+	loop
+	src="/videos/fork_workspace_demo.mp4"
+/>
+
+
+## Advanced setup: Cross-instance deployment (promotion)
+
+When you have workspaces in different instances, for example in a setup with a staging instance and a prod instance, you might want to deploy changes from one workspace to the other. One way to do this is through a cross-instance promotion: when changes are made in the first "staging" workspace, a branch with a name corresponding to the item is created in the second workspace's repo. A PR is automatically created through the CI/CD. Changes are reviewed, and once the PR is merged the changes are reflected in the "production" workspace.
+
+**Requirements**:
+- Git sync should be setup on both workspaces, so that they're both syncing changes with their respective repositories.
+
+![Advanced cross-instance deployment (promotion)](../4_local_development/local_development.png 'Promotion')

docs/advanced/12_deploy_to_prod/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. 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')
+![Promotion workflow](../4_local_development/local_development.png 'Promotion workflow')
 
 <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 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/20_workspace_forks/index.mdx

@@ -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/4_local_development/index.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="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>