bidirectional sync

Author: forstisabella

Diff for: src/segment-app/extensions/git.md

@@ -86,21 +86,42 @@ For more information on using Terraform, visit [Terraform's documentation](https
 
 ## 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 will not apply any changes unless the pull request is s[ecigfied pull request has met all mere requirements and the pull request is able to be merged.
+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 will not apply any changes unless the pull request has met all merge requirements and can be merged.
+
+Bidirectional sync only supports: 
+- Explicit values (secrets 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 t0 o 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 thje Segment app, navigate to **Settings > Edxtentions > Git Sync** page and enabling the **Git sync bidirectional sync** setting. 
+3. **Navigate to the Segment app and enable Git sync bidirectional sync.** From the Segment app, navigate to **Settings > Extentions > Git Sync** page and enabling the **Git sync bidirectional sync** setting. 
 
 ### Use 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, and submit a pull request with 
+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