Configuring Push Mirroring in Forgejo to Keep Repositories in Sync with External Git Hosts

Problem: Keeping a Forgejo repository in sync with an external Git host

When you host code on Forgejo but also need the same repository available on another service—such as GitHub, GitLab, or a backup server—you must push changes manually or rely on external scripts. This creates a window where the two copies diverge and adds operational overhead.

Thesis: Forgejo’s built‑in push‑mirror feature lets you configure a repository to automatically push every change to a remote Git server, keeping the copies identical without extra tooling.

How mirroring works in Forgejo

For each repository you can define one or more mirror URLs. When a push arrives, Forgejo enqueues a background job that runs git push --mirror . The job respects the same authentication mechanisms you configure (HTTP basic auth with username/password or token, or SSH keys stored in the Forgejo server’s .ssh directory). Mirrors are processed sequentially; failures are logged and retried according to the queue’s back‑off policy.

Worked example: Configure a push mirror to GitHub

1. Log in to Forgejo with an account that has administrative rights on the target repository.
2. Open the repository, choose Settings → Mirror.
3. In the Mirror URL field enter the destination, for example https://github.com/username/repo.git.
4. If the destination requires authentication, select Username/Password and provide your GitHub username and a personal access token (PAT) with the repo scope. For SSH, place the private key in /var/lib/forgejo/.ssh/id_rsa (ensure the file is owned by the Forgejo user and mode 600) and leave the username/password fields blank.
5. Set Mirror direction to Push only (the default).
6. Click Save mirror. Forgejo will immediately queue a test push.
7. After a few seconds, open the Activity tab of the repository; you should see a line like Mirror push to https://github.com/username/repo.git succeeded.

Limitations and trade‑offs

• Mirroring is unidirectional unless you configure a second mirror back to Forgejo; concurrent pushes on both sides can create conflicts that must be resolved manually.
• The mirror job runs on the Forgejo server’s CPU and network; a very busy instance may see increased latency during peak push periods.
• If you enable Force push on the mirror (available in advanced settings), the remote history can be rewritten, which may destroy data on the destination.
• Authentication credentials are stored in Forgejo’s database; ensure the database is backed up and access‑restricted.

How to verify the mirror is working

1. Make a test commit in the Forgejo repository and push it.
2. Check the destination host (e.g., GitHub) to confirm the commit appears.
3. Open the Forgejo Admin Panel, navigate to Mirrors, and locate your repository; the panel shows the last success timestamp and any error messages.
4. Inspect the log file /var/log/forgejo/forgejo.log for lines containing Mirror push.

With these steps you have a reliable, low‑maintenance way to keep Forgejo repositories synchronized with external Git services, leveraging the project’s lightweight, Go‑based architecture and its commitment to community‑governed, software‑freedom principles.