FossilRepo

fossilrepo / docs / architecture / sync-bridge.md

Source Rendered

Blame History Raw 80 lines

1	`# Sync Bridge`
2
3	`The sync bridge mirrors Fossil repositories to GitHub and GitLab as downstream read-only copies.`
4
5	`## How It Works`
6
7	```mermaid
8	`flowchart LR`
9	`Fossil["Fossil Repo<br/>(source of truth)"] --> Bridge["Sync Bridge<br/>(Celery task)"]`
10	`Bridge --> Git["Git Export"]`
11	`Git --> GitHub["GitHub Mirror"]`
12	`Git --> GitLab["GitLab Mirror"]`
13	```
14
15	`The bridge:`
16
17	`1. Exports Fossil commits as Git commits`
18	`2. Pushes to configured Git remotes`
19	`3. Optionally syncs tickets to GitHub/GitLab Issues`
20	`4. Optionally syncs wiki pages to repo docs`
21
22	`## What Gets Synced`
23
24	`\| Fossil Artifact \| Git Target \| Configurable \|`
25	`\|---\|---\|---\|`
26	`\| Commits \| Git commits \| Always \|`
27	`\| Tags \| Git tags \| Always \|`
28	`\| Branches \| Git branches \| Always \|`
29	`\| Tickets \| GitHub/GitLab Issues \| Optional \|`
30	`\| Wiki \| Repository docs \| Optional \|`
31
32	`## Configuration`
33
34	`Set up mirroring through the Django management UI or environment variables:`
35
36	```bash
37	`# GitHub mirror`
38	`GITHUB_TOKEN=ghp_xxxxxxxxxxxx`
39
40	`# GitLab mirror`
41	`GITLAB_TOKEN=glpat-xxxxxxxxxxxx`
42	```
43
44	`Per-repository mirror configuration is managed in the dashboard under Repository Settings > Sync.`
45
46	`## Sync Modes`
47
48	`### On-Demand`
49
50	`Trigger a sync manually from the dashboard or CLI:`
51
52	```bash
53	`docker compose exec django python manage.py fossil_sync my-project`
54	```
55
56	`### Scheduled`
57
58	`Configure a Celery Beat schedule to sync at regular intervals:`
59
60	```python
61	`# Runs every 15 minutes`
62	`CELERY_BEAT_SCHEDULE = {`
63	`'sync-all-repos': {`
64	`'task': 'fossil.tasks.sync_all',`
65	`'schedule': 900.0,`
66	`},`
67	`}`
68	```
69
70	`### Upstream Pull`
71
72	`Pull updates from a remote Fossil server into your local instance:`
73
74	```bash
75	`docker compose exec django python manage.py fossil_pull my-project`
76	```
77
78	`!!! warning "Direction matters"`
79	`The sync bridge is one-way: Fossil to Git. Changes pushed directly to a Git mirror will be overwritten on the next sync. Always push to the Fossil repo.`
80

FossilRepo

Keyboard Shortcuts