Run a Git bridge¶
A Git bridge keeps a TOVIO repository and a Git remote in sync in both directions, so a mixed team can migrate gradually: some people work native TOVIO, others stay on GitHub, GitLab, or Gitea, and commits flow both ways. This is the bridge you reach for when a one-time import isn't enough because you're not ready to move everyone at once.
Available in Phase 3
tovio git bridge <remote> --bidirectional runs a complete two-way cycle. It supports local bare
repositories and the installed Git transport/credential stack used for GitHub, GitLab, and Gitea.
Add --watch [<seconds>] to keep cycling in the foreground.
When to use a bridge¶
Reach for a bridge when both of these are true:
- You want some teammates on TOVIO now, without waiting for everyone.
- The people still on Git need to keep seeing each other's commits — and yours — without learning a new tool yet.
If instead you just want to move a repository to TOVIO once and not look back, you don't need a bridge — import from Git is the whole job.
Run a bridge cycle¶
A bridge is set up once, then runs quietly. The shape of it:
Each invocation fetches Git branches (and tags) into git/<remote-id>/*, then publishes the native TOVIO
lanes that advanced since the last cycle under Git's refs/heads/tovio/*. <remote-id> is a short hash of
the remote string, so one repository can bridge several remotes without their namespaces colliding. Run it
again whenever either side advances, schedule the same finite command in CI, or pass --watch [<seconds>]
(default 60) to keep cycling in the foreground until you press Ctrl-C. It is never a hidden daemon, and a
cycle that fails (a non-fast-forward, say) is reported while the watch keeps going.
What crosses the bridge — and what doesn't¶
The bridge moves ordinary commits both ways. A few things are handled specially:
| Crosses the bridge | Handling |
|---|---|
| Commits and branches | Flow both directions: Git branches arrive as git/<remote-id>/<branch>, TOVIO lanes publish as tovio/<lane>. |
| Tags | Come in from Git as git/<remote-id>/<tag>; a moved Git tag never re-points an existing TOVIO tag. TOVIO tags are not published to Git. |
| Change IDs and agent provenance | Ride out to Git as commit trailers, so identity survives the round trip where possible. |
| Policy-protected files | Ciphertext only, with a warning — never plaintext. See the callout below. |
| Paths with an unresolved conflict | Skipped on export, with a warning — resolve conflicts before a bridge cycle. |
Encrypted files cannot be made readable on the Git side
TOVIO's whole point is that policy-protected files are encrypted, and a Git remote has no way to enforce TOVIO policies. The bridge therefore exports protected objects as ciphertext (with a warning) — it will not push plaintext secrets to the Git remote. Plan for protected paths to be readable only on the TOVIO side of a mixed team.
When the two sides advance¶
Git and TOVIO never compete for one main ref. A Git-native main arrives as
git/<remote-id>/main; TOVIO main publishes as Git tovio/main. You reconcile them explicitly with the
ordinary TOVIO review/land flow. A non-fast-forward Git publication is refused without force and returns
TVO-MIG-006; neither history is discarded. Transport, credential, timeout, and translation failures
report TVO-MIG-004 instead.
The bridge writes .tovio/git-bridge/<remote-id>/commits.tsv atomically so Git OIDs, TOVIO addresses, and
Change IDs remain stable across repeated cycles. Every underlying Git command is non-interactive and has a
120-second deadline.
Where to go next¶
- Import from Git — the one-way path for teams that do not need continuous coexistence; often all a team needs.
- Run CI/CD against TOVIO — keep your pipelines running across the bridge during the transition.
- Collaboration & files — clone, sync, review, and lane protection for the native-TOVIO side of the team.
- On-premise — the bridge can target Git directly; if you're also planning a TOVIO collaboration service inside your own perimeter, you'll likely run one.
Last reviewed September 9, 2026
Suggest an improvement to this page Not for security reports — see disclosure