Connecting Git Sync is the easy part. Operating it safely in a real team workflow is where most documentation programs either gain confidence or accumulate hidde...
Connecting Git Sync is the easy part. Operating it safely in a real team workflow is where most documentation programs either gain confidence or accumulate hidde...
Connecting Git Sync is the easy part. Operating it safely in a real team workflow is where most documentation programs either gain confidence or accumulate hidden friction. This guide explains how to run Git Sync as an ongoing system rather than as a one-time setup checkbox.
Who this is for
- teams using Doxbrix with GitHub or GitLab
- teams combining editor-based authoring with repository-based workflows
- teams that want predictable docs publishing without accidental sync surprises
What Git Sync changes operationally
When Git Sync is active, documentation can move in both directions:
- repository changes can update the project
- editor changes can commit back to the repository
That is powerful, but it also means the team needs shared expectations around:
- which branch is authoritative
- who edits where
- how conflicts are resolved
- how publish timing relates to repository timing
Step 1 — Choose the tracked branch intentionally
When you configure Git Sync, pick the branch that should represent live synchronized documentation.
For most teams, this is the default integration branch rather than a feature branch. Use a branch that already has stable operational meaning for the repository.
Avoid:
- rotating feature branches
- personal branches
- experimental branches that are not part of the team’s normal release discipline
Step 2 — Decide how authors are expected to work
Before the team starts using Git Sync broadly, document which of these models you are using:
Model A — App-first
Use the Doxbrix editor as the primary authoring surface and let Doxbrix commit changes back to the repository.
Best for:
- writer-led teams
- teams that want a visual publishing workflow
- teams where engineers still want repository history
Model B — Repo-first
Use repository changes as the primary authoring path and let Git Sync bring them into Doxbrix.
Best for:
- engineering-led docs-as-code teams
- monorepo-based documentation programs
- teams already disciplined around pull requests and branch review
Model C — Mixed model
Allow both repository and editor authorship, but define when each should be used.
Best for:
- mixed writer and engineer teams
- teams where some content is maintained in app and some in code
Step 3 — Define conflict expectations up front
Conflicts are not a sign that Git Sync is broken. They are a sign that two sources changed overlapping content without a shared sequence.
Reduce conflicts by agreeing on:
- whether certain sections are editor-owned or repo-owned
- whether large restructures happen in one place first
- whether urgent in-app edits should later be normalized in the repository
If the same content is heavily edited in both places at once, conflicts are a predictable outcome.
Step 4 — Use project settings to keep the workflow visible
Keep the team aligned by making sure the project’s configuration supports the Git-based workflow:
- use the right Editor mode and Source mode default
- make sure page templates and structure are stable enough for repository work
- confirm project members understand whether a change should happen in the app or in Git
This reduces accidental use of the wrong surface for a high-risk change.
Step 5 — Handle structural changes carefully
Large changes to spaces, groups, page movement, or page creation deserve more care than small text edits.
Recommended practice:
- batch larger structural changes deliberately
- avoid simultaneous restructure work in the editor and repository
- verify the final navigation after sync completes
This is especially important because navigation changes have reader-facing impact immediately once they are published or synced into the live workflow.
Step 6 — Treat sync state as operational data
If the project is Git-backed, check sync status when something looks wrong rather than assuming the content itself is broken.
Look for signs such as:
- repository changes not appearing yet
- editor changes not reaching the repository
- imported content still processing
- conflict or warning states in the sync flow
Resolve sync-state uncertainty before making more edits on top of it.
Step 7 — Decide how pull requests fit into the docs workflow
If the repository is your review layer, clarify:
- whether docs changes require pull requests before they become authoritative
- whether app-originated commits are later reviewed in Git
- whether emergency editor changes are allowed directly and then normalized later
There is no single right answer, but there should be one team answer.
Step 8 — Recover cleanly from drift
If the app and repository begin to feel out of sync:
- pause new overlapping edits
- identify which source has the intended latest state
- resolve the mismatch before continuing broader work
- communicate the recovered baseline to the team
The worst recovery pattern is continued editing during uncertainty.
Recommended operating rules
- one tracked branch per synced docs workflow
- clear authoring ownership by content type or team
- no large restructures in two surfaces at once
- check sync state before debugging content anomalies
- review conflict patterns as workflow problems, not one-off annoyances