Bidirectional Sync docs

src/segment-app/extensions/git.md

@@ -4,9 +4,9 @@ title: Git Sync Extension
 
 Segment's Git extension lets you manage versioning by syncing changes you make in your Segment workspace to a Git repository.
 
-Git Sync supports one-way synchronization from Segment to Git. This sync captures the current state of your workspace through a full sync and includes all new records and changes for supported resources.
+Git Sync supports synchronization from Segment to Git. When you sync data from Segment to Git, you capture the current state of your workspace through a full sync and includes all new records and changes for supported resources. 
 
-Segment doesn't support syncing changes from Git back to Segment.
+You can use [bidirectional sync](#bidirectional-sync) to sync data from Git to Segment. After you enable bidirectional sync, Segment automatically listens for pull requests in your repository and manages all related workspace changes. 
 
 ## Set up Git Sync
 
@@ -84,6 +84,45 @@ To manage Segment resources using Git and Terraform, follow these steps:
 
 For more information on using Terraform, visit [Terraform's documentation](https://developer.hashicorp.com/terraform/docs){:target="_blank"}.
 
+## Bidirectional Sync
+
+Bidirectional sync builds on top of the Git Sync extension and lets you manage your Segment workspace directly in GitHub. After you configure and enable bidirectional sync, Segment automatically listens for pull requests in your repository and manages all related workspace changes. Segment only applies changes when you comment `segment apply` on pull requests that can be successfully merged.
+
+Bidirectional sync only supports: 
+- Explicit values ([secrets](#use-secrets-with-bidirectional-sync) require additional configuration)
+- [Segment resources compatible with Git sync](#working-with-git-sync)
+
+Bidirectional sync does not support variables, references to other resources, or resources from other providers.
+
+> warning "Bidirectional sync can lead to broad workspace changes, including data loss"
+> When using bidirectional sync to manage your Segment resources, verify that your specified plan matches the changes you expected. Unexpected changes can include data loss.
+
+### Set up bidirectional sync
+
+To set up bidirectional sync in your workspace: 
+
+1. **Navigate to the Git Sync settings page to verify that your Git Sync integration is set up with Segment's GitHub App integration.** If it isn't, you can change the connection type under **Settings > Extensions > Git Sync > Manage Configuration**. If you were previously using the GitHub App integration, you might need to accept additional GitHub permissions that allow Segment to listen for the relevant events. 
+2. **Add branch protection to your GitHub repository**. You can update your branch protections by opening GitHub and navigating to **Settings > Rules > Rulesets** and adding the Segment Extensions app to the **Bypass list**. 
+3. **Navigate to the Segment app and enable Git sync bidirectional sync.** From the Segment app, navigate to **Settings > Extentions > Git Sync** page and enable the **Git sync bidirectional sync** setting. 
+
+### Use bidirectional sync
+
+To apply changes to your workspace using bidirectional sync: 
+
+1. Create a branch off of the branch specified in your Git Sync configuration, make the changes you'd like to see in your workspace, then submit a pull request with your changes.
+    - To add a new resource, add a *new* configuration file to the corresponding resource directory. Segment does not support multiple resources within the same file. The name does not matter, as it will be overwritten with a new ID after Segment creates the resource. 
+2. Segment calculates the changes required to reflect those changes and outputs the planned changes to a comment directly on the pull request.
+3. Carefully double check that the planned changes match your desired changes and request approval from any stakeholders required before merging the pull request. 
+4. Run `segment apply` to apply the planned changes. 
+
+#### Use secrets with bidirectional sync
+
+To use secrets in your bidirectional sync workflow: 
+
+1. Navigate to **Settings > Extensions > Git Sync > Manage Configuration** and upload your secret to the **Secrets** table.
+2. When referencing your secret, use `@@<secret_name>@@` in place of your secret, wherever applicable. Secrets are automatically hidden in a bidirectional sync output, but if you are not using them in a designated secret field, like Source/Destination key settings, for example, they might be written in plaintext to the repository as part of the regular syncing process. 
+3. Plan and apply the changes as usual. 
+
 ## Git Connections
 
 Git Connections enable Segment to sync data with your preferred Git repository through supported like SSH and token-based authentication.
@@ -114,3 +153,4 @@ This error can occur if there are issues with your Git connection settings or pe
 - Your credentials have write access to the Git repository, as Segment requires this to sync changes.
 - Your repository is hosted by GitHub, GitLab, or Bitbucket (Segment doesn't support self-hosted repositories).
 - Branch protections are disabled on the repository.
+