Setting Up Repository Mirroring in Forgejo for Reliable Sync

The problem: keeping a Forgejo repo in sync with an external Git server

Teams often need a Forgejo-hosted repository to stay identical to a mirror on another Git service (e.g., a backup on GitHub or an internal GitLab). Manual pushes are error‑prone and forgettable, especially when multiple contributors work on the same branch.

Thesis: Forgejo’s built‑in mirroring feature can automate one‑way or bidirectional sync with minimal configuration and no external cron.

How mirroring works in Forgejo

Mirroring is configured per repository and runs as a background job in Forgejo’s built‑in queue. You choose a direction (pull or push), supply the remote URL, authentication, and a sync interval. The worker respects Git LFS objects and can limit sync to specific refs via refspec patterns.

Worked example: configuring pull mirroring from Forgejo to a remote GitHub repo

1. Navigate to the repository in Forgejo, open Settings → Repository → Mirroring.
2. Set Mirror direction to Pull (remote → Forgejo).
3. Enter the remote URL, e.g. https://github.com/example/upstream.git.
4. Choose Authentication method – for HTTPS you can use a personal access token; for SSH add the deploy key to Forgejo’s SSH / GPG keys page.
5. Set Sync interval to 5 minutes for a quick test.
6. Optionally limit to refs/heads/main using the Refspec field.
7. Click Save mirroring settings.

After saving, Forgejo queues a mirror job. You can watch its progress under Admin → Monitoring → Queue. When the job runs, it fetches any new commits from GitHub and updates the local Forgejo repo.

Verifying the mirror works

• Push a test commit to the GitHub repository.
• Wait up to the sync interval (or trigger the job manually via the queue UI).
• Open the Forgejo repository and confirm the commit appears.
• Check the queue log for a success status; any failure will be shown with an error message and retry count.

Limitation: divergence causes sync failure

If the local Forgejo branch and the remote branch have diverged (e.g., a force push on one side), the mirror worker will abort and report a conflict. Mirroring does not attempt to merge; you must resolve the divergence manually before sync can resume.

Practical way to check for divergence

After a suspected failure, run git ls-remote refs/heads/main on the Forgejo server and compare the SHA with git rev-parse refs/remotes/origin/main. If they differ, you have divergence and need to decide which side to keep.

Actionable closing

Forgejo mirroring gives teams a low‑maintenance way to keep repositories aligned across services. Start with a short sync interval on a test repo, verify success via the queue logs, then extend to production branches. Keep an eye on the queue for failures, and remember that any history divergence will require manual intervention before the mirror can continue.