Forgejo Repository Mirroring: Sync Git Refs Without Moving Issues or Pull Requests

The problem: keeping an external Git repository visible in Forgejo

You maintain a Forgejo instance for internal projects, but a team's active code lives in an external Git remote—perhaps a vendor's GitLab server, a public GitHub repository, or another Forgejo instance. Developers need to browse the code, create local clones, and trigger CI from Forgejo without manually copying branches every time an upstream maintainer pushes.

Forgejo includes built-in repository mirroring. The useful takeaway is that it automates synchronization of Git refs and objects—branches, tags, and commit history—but it does not copy Forgejo-specific data such as issues, pull requests, wiki pages, or release descriptions. Treat it as a code mirror, not a full project migration.

Pull mirroring versus push mirroring

Forgejo supports two directions. In a pull mirror, Forgejo fetches from an external URL and updates the local repository on a schedule you choose. In a push mirror, Forgejo sends its local refs to an external destination. Pull mirroring is usually safer for consuming upstream code because it does not write to the remote. Push mirroring can overwrite refs on the destination remote, so review force-push behavior before pointing it at a shared upstream.

Authentication can use HTTPS with a username and password or token, or an SSH key registered in Forgejo. Credentials are stored on the Forgejo host, so limit access to repository settings and rotate tokens if an upstream remote is compromised.

What gets replicated

• Branch refs and commit objects
• Tag refs
• Mirror status, last sync time, and error messages in repository settings

What stays on the source

• Issues and issue comments
• Pull requests and review comments
• Wiki pages
• Release descriptions and attachments

Worked example: configure a pull mirror

Run these steps in the Forgejo web UI as a repository owner or admin. Exact menu paths vary across Forgejo releases because Forgejo is an active fork of Gitea; open your repository settings and look for a Mirror or Repository mirroring section.

1. Open the repository in Forgejo and navigate to Settings > Mirror (or the equivalent mirroring section in your installed version).
2. Enter the external Git URL, for example https://git.example.com/upstream/repo.git.
3. Choose Pull mirroring.
4. Provide authentication if required: an HTTPS token or username/password, or select a registered SSH key.
5. Set a sync interval, such as every 15 minutes, or leave manual sync only while you test.
6. Save the mirror configuration, then trigger a manual sync.

Expected check: the mirror log in repository settings should show a successful sync and update the last sync time. If authentication fails or the network is unreachable, Forgejo typically displays an error message in the same settings page and may write details to the Forgejo system logs.

Risk: short intervals and large repositories increase disk, network, and CPU usage on the Forgejo server. Start with a longer interval and monitor storage growth before scheduling frequent syncs.

Verify the mirror independently

Do not rely only on the Forgejo status page. After a sync completes, compare refs between the upstream and the mirror from a terminal where you have network access to both URLs:

git ls-remote https://git.example.com/upstream/repo.git
git ls-remote https://forgejo.example.com/owner/mirror-repo.git

Compare the branch and tag lines. The commit hashes should match for refs that have completed a sync cycle. You can also query the Forgejo repository mirroring API for the mirror record and inspect the last sync time and error fields. API endpoint names and response fields vary by Forgejo release, so confirm the paths against your installed version's documentation.

To confirm failure handling, temporarily introduce a bad credential or block network access, then run a manual sync. The failure should appear in the mirror settings and Forgejo system logs. Restore the original credential afterward.

Limitations and rollback

Mirroring replicates Git data only. If your team depends on issues, pull requests, or wiki pages in the external repository, those will not appear in Forgejo. You will need a separate migration or integration for that data.

Enabling mirroring changes state: Forgejo stores credentials and begins creating or updating refs in the local repository. To roll back, open Repository Settings > Mirror, disable or delete the mirror configuration, and stop scheduled syncs. Existing refs already fetched into the Forgejo repository remain unless you delete them manually or remove the repository.

Actionable closing

Use Forgejo mirroring when you need an up-to-date read-only copy of an external Git repository for browsing, cloning, or internal CI. Configure authentication carefully, start with a conservative sync interval, verify refs with git ls-remote, and remember that Forgejo-specific collaboration data stays where it originated. Check your installed Forgejo release for the exact settings path and API names before rolling this out to production.