diff --git a/docs/integrations/github.md b/docs/integrations/github.md
index 613eec8..42cf88f 100644
--- a/docs/integrations/github.md
+++ b/docs/integrations/github.md
@@ -30,3 +30,35 @@ OpenTrace requests read-only access to:
 - Repository contents
 - Issues
 - Organization membership (for org repos)
+
+## Changing the Synced Branch
+
+By default, OpenTrace syncs the default branch of each repository (typically `main` or `master`). You can change which branch is synced for any repository through the UI or API.
+
+### Using the UI
+
+1. Navigate to **Integrations > GitHub** in the OpenTrace UI
+2. Find the repository you want to configure under **Syncs**
+3. Click the 3 vertical dots and open its sync settings
+4. Click the edit icon (✏️) next to the **Branch** field
+5. Enter the new branch name (e.g., `develop`, `staging`, `feature/new-ui`)
+6. Click the checkmark (✓) to save
+7. Confirm the change by typing the repository name when prompted
+
+**Important Notes:**
+
+- Changing the branch will trigger a reindex of the repository code
+- All existing code index data for that repository will be removed
+- The reindexing process may take several minutes depending on repository size
+- The branch must exist in the repository before you can sync it
+
+### Using the API
+
+You can also change the branch programmatically using the API.  This is documented under [api.opentrace.ai/openapi](https://api.opentrace.ai/openapi/) - see the section on integrations.
+
+### Branch Configuration Behavior
+
+- **First-time sync**: Uses the repository's default branch from GitHub
+- **Custom branch**: Once set, OpenTrace continues using your configured branch
+- **Branch deletion**: If the configured branch is deleted, syncing will fail until you update to a valid branch
+- **Empty value**: Setting `code_branch` to an empty string or removing it will revert to using the repository's default branch
diff --git a/docs/integrations/gitlab.md b/docs/integrations/gitlab.md
index cf0336e..0e7610f 100644
--- a/docs/integrations/gitlab.md
+++ b/docs/integrations/gitlab.md
@@ -26,3 +26,35 @@ You can exclude specific files or directories from analysis using [`.otignore` f
 ## Self-Hosted GitLab
 
 For self-hosted GitLab instances, you may need to configure the GitLab URL in your OpenTrace settings before connecting.
+
+## Changing the Synced Branch
+
+By default, OpenTrace syncs the default branch of each project (typically `main` or `master`). You can change which branch is synced for any project through the UI or API.
+
+### Using the UI
+
+1. Navigate to **Integrations > GitLab** in the OpenTrace UI
+2. Find the project you want to configure under **Syncs**
+3. Click the 3 vertical dots and open its sync settings
+4. Click the edit icon (✏️) next to the **Branch** field
+5. Enter the new branch name (e.g., `develop`, `staging`, `feature/new-ui`)
+6. Click the checkmark (✓) to save
+7. Confirm the change by typing the project name when prompted
+
+**Important Notes:**
+
+- Changing the branch will trigger a reindex of the project code
+- All existing code index data for that project will be removed
+- The reindexing process may take several minutes depending on project size
+- The branch must exist in the project before you can sync it
+
+### Using the API
+
+You can also change the branch programmatically using the API.  This is documented under [api.opentrace.ai/openapi](https://api.opentrace.ai/openapi/) - see the section on integrations.
+
+### Branch Configuration Behavior
+
+- **First-time sync**: Uses the project's default branch from GitLab
+- **Custom branch**: Once set, OpenTrace continues using your configured branch
+- **Branch deletion**: If the configured branch is deleted, syncing will fail until you update to a valid branch
+- **Empty value**: Setting `code_branch` to an empty string or removing it will revert to using the project's default branch