From 867f87a1ddce7055a40056b1a5d1e9988070b211 Mon Sep 17 00:00:00 2001 From: Stephen Bryant Date: Mon, 9 Feb 2026 17:07:30 +0100 Subject: [PATCH 1/4] Add branch configuration documentation for GitHub and GitLab integrations Added comprehensive "Changing the Synced Branch" sections to both GitHub and GitLab integration documentation pages, including: - Step-by-step UI instructions for changing the synced branch - API examples with complete curl commands and parameter descriptions - Instructions for finding integration and sync IDs - Explanation of branch configuration behavior and edge cases - Important notes about reindexing and data removal Both integrations use the same backend API endpoint and settings mechanism (code_branch setting via POST /v1/setup/{integrationID}/sync/{syncID}). Co-Authored-By: Claude Sonnet 4.5 --- docs/integrations/github.md | 72 +++++++++++++++++++++++++++++++++++++ docs/integrations/gitlab.md | 72 +++++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+) diff --git a/docs/integrations/github.md b/docs/integrations/github.md index 613eec8..0f2316d 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -30,3 +30,75 @@ 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 +3. Click the repository to 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: + +```bash +curl -X POST \ + https://api.opentrace.io/integrations/v1/setup/{integrationID}/sync/{syncID} \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "settings": { + "code_branch": "develop" + }, + "merge": true, + "resyncs": ["code"], + "purge": true + }' +``` + +**Parameters:** + +- `integrationID` - Your GitHub integration ID +- `syncID` - The repository's sync ID (typically the repository ID) +- `settings.code_branch` - The name of the branch to sync +- `merge` - Set to `true` to merge with existing settings (recommended) +- `resyncs` - Array of sync types to trigger (`["code"]` for code sync) +- `purge` - Set to `true` to remove old data before resyncing (recommended when changing branches) + +### Finding Integration and Sync IDs + +To get your integration and sync IDs: + +```bash +# List all integrations +curl -X GET \ + https://api.opentrace.io/integrations/v1/setup \ + -H "Authorization: Bearer YOUR_API_TOKEN" + +# Get syncs for a specific integration +curl -X GET \ + https://api.opentrace.io/integrations/v1/setup/{integrationID} \ + -H "Authorization: Bearer YOUR_API_TOKEN" +``` + +### 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..23b3b32 100644 --- a/docs/integrations/gitlab.md +++ b/docs/integrations/gitlab.md @@ -26,3 +26,75 @@ 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 +3. Click the project to 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: + +```bash +curl -X POST \ + https://api.opentrace.io/integrations/v1/setup/{integrationID}/sync/{syncID} \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "settings": { + "code_branch": "develop" + }, + "merge": true, + "resyncs": ["code"], + "purge": true + }' +``` + +**Parameters:** + +- `integrationID` - Your GitLab integration ID +- `syncID` - The project's sync ID (typically the project ID) +- `settings.code_branch` - The name of the branch to sync +- `merge` - Set to `true` to merge with existing settings (recommended) +- `resyncs` - Array of sync types to trigger (`["code"]` for code sync) +- `purge` - Set to `true` to remove old data before resyncing (recommended when changing branches) + +### Finding Integration and Sync IDs + +To get your integration and sync IDs: + +```bash +# List all integrations +curl -X GET \ + https://api.opentrace.io/integrations/v1/setup \ + -H "Authorization: Bearer YOUR_API_TOKEN" + +# Get syncs for a specific integration +curl -X GET \ + https://api.opentrace.io/integrations/v1/setup/{integrationID} \ + -H "Authorization: Bearer YOUR_API_TOKEN" +``` + +### 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 From bb2993f2354c30ec5a16c12d09d73a2c1a0c9e01 Mon Sep 17 00:00:00 2001 From: Stephen Bryant Date: Mon, 9 Feb 2026 21:44:36 +0100 Subject: [PATCH 2/4] Replaced API usage documentation (for branch changing) with a link to the API documentation. --- docs/integrations/github.md | 42 +------------------------------------ docs/integrations/gitlab.md | 42 +------------------------------------ 2 files changed, 2 insertions(+), 82 deletions(-) diff --git a/docs/integrations/github.md b/docs/integrations/github.md index 0f2316d..db9616d 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -54,47 +54,7 @@ By default, OpenTrace syncs the default branch of each repository (typically `ma ### Using the API -You can also change the branch programmatically using the API: - -```bash -curl -X POST \ - https://api.opentrace.io/integrations/v1/setup/{integrationID}/sync/{syncID} \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "settings": { - "code_branch": "develop" - }, - "merge": true, - "resyncs": ["code"], - "purge": true - }' -``` - -**Parameters:** - -- `integrationID` - Your GitHub integration ID -- `syncID` - The repository's sync ID (typically the repository ID) -- `settings.code_branch` - The name of the branch to sync -- `merge` - Set to `true` to merge with existing settings (recommended) -- `resyncs` - Array of sync types to trigger (`["code"]` for code sync) -- `purge` - Set to `true` to remove old data before resyncing (recommended when changing branches) - -### Finding Integration and Sync IDs - -To get your integration and sync IDs: - -```bash -# List all integrations -curl -X GET \ - https://api.opentrace.io/integrations/v1/setup \ - -H "Authorization: Bearer YOUR_API_TOKEN" - -# Get syncs for a specific integration -curl -X GET \ - https://api.opentrace.io/integrations/v1/setup/{integrationID} \ - -H "Authorization: Bearer YOUR_API_TOKEN" -``` +You can also change the branch programmatically using the API. This is documented under https://api.opentrace.ai/openapi/ - see the section on integrations. ### Branch Configuration Behavior diff --git a/docs/integrations/gitlab.md b/docs/integrations/gitlab.md index 23b3b32..c332324 100644 --- a/docs/integrations/gitlab.md +++ b/docs/integrations/gitlab.md @@ -50,47 +50,7 @@ By default, OpenTrace syncs the default branch of each project (typically `main` ### Using the API -You can also change the branch programmatically using the API: - -```bash -curl -X POST \ - https://api.opentrace.io/integrations/v1/setup/{integrationID}/sync/{syncID} \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "settings": { - "code_branch": "develop" - }, - "merge": true, - "resyncs": ["code"], - "purge": true - }' -``` - -**Parameters:** - -- `integrationID` - Your GitLab integration ID -- `syncID` - The project's sync ID (typically the project ID) -- `settings.code_branch` - The name of the branch to sync -- `merge` - Set to `true` to merge with existing settings (recommended) -- `resyncs` - Array of sync types to trigger (`["code"]` for code sync) -- `purge` - Set to `true` to remove old data before resyncing (recommended when changing branches) - -### Finding Integration and Sync IDs - -To get your integration and sync IDs: - -```bash -# List all integrations -curl -X GET \ - https://api.opentrace.io/integrations/v1/setup \ - -H "Authorization: Bearer YOUR_API_TOKEN" - -# Get syncs for a specific integration -curl -X GET \ - https://api.opentrace.io/integrations/v1/setup/{integrationID} \ - -H "Authorization: Bearer YOUR_API_TOKEN" -``` +You can also change the branch programmatically using the API. This is documented under https://api.opentrace.ai/openapi/ - see the section on integrations. ### Branch Configuration Behavior From 6b5d805640f4e16d6eb1564e0ac672ecc27007db Mon Sep 17 00:00:00 2001 From: Stephen Bryant Date: Tue, 10 Feb 2026 10:30:43 +0100 Subject: [PATCH 3/4] Reformatted the links to the API to be clickable in HTML. --- docs/integrations/github.md | 2 +- docs/integrations/gitlab.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/integrations/github.md b/docs/integrations/github.md index db9616d..de3b15c 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -54,7 +54,7 @@ By default, OpenTrace syncs the default branch of each repository (typically `ma ### Using the API -You can also change the branch programmatically using the API. This is documented under https://api.opentrace.ai/openapi/ - see the section on integrations. +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 diff --git a/docs/integrations/gitlab.md b/docs/integrations/gitlab.md index c332324..61113b4 100644 --- a/docs/integrations/gitlab.md +++ b/docs/integrations/gitlab.md @@ -50,7 +50,7 @@ By default, OpenTrace syncs the default branch of each project (typically `main` ### Using the API -You can also change the branch programmatically using the API. This is documented under https://api.opentrace.ai/openapi/ - see the section on integrations. +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 From 56a95c9a054085922804b49d8ac7a5a1ed8e93a3 Mon Sep 17 00:00:00 2001 From: Stephen Bryant Date: Tue, 10 Feb 2026 10:52:54 +0100 Subject: [PATCH 4/4] Minor correction for UI instructions. --- docs/integrations/github.md | 4 ++-- docs/integrations/gitlab.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/integrations/github.md b/docs/integrations/github.md index de3b15c..42cf88f 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -38,8 +38,8 @@ By default, OpenTrace syncs the default branch of each repository (typically `ma ### Using the UI 1. Navigate to **Integrations > GitHub** in the OpenTrace UI -2. Find the repository you want to configure -3. Click the repository to open its sync settings +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 diff --git a/docs/integrations/gitlab.md b/docs/integrations/gitlab.md index 61113b4..0e7610f 100644 --- a/docs/integrations/gitlab.md +++ b/docs/integrations/gitlab.md @@ -34,8 +34,8 @@ By default, OpenTrace syncs the default branch of each project (typically `main` ### Using the UI 1. Navigate to **Integrations > GitLab** in the OpenTrace UI -2. Find the project you want to configure -3. Click the project to open its sync settings +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