Configuring Automatic Repository Mirroring in Forgejo

The Problem: Keeping Distributed Repositories in Sync

Maintaining a local copy of an external repository—whether for backup, compliance, or reducing latency for a distributed team—often leads to manual git clone and git push cycles. Manual updates are prone to human error and result in stale code.

The solution is Forgejo's built-in mirroring feature. This allows a Forgejo instance to act as a mirror that automatically polls a source repository (from GitHub, GitLab, or another Forgejo instance) and synchronizes branches, tags, and commits without manual intervention.

Prerequisites

• An active Forgejo installation (v6.0 or later recommended).
• Administrative or Owner permissions for the target repository in Forgejo.
• A source repository URL (HTTPS or SSH).
• A Personal Access Token (PAT) or SSH key from the source provider if the repository is private.

Setting Up the Mirror

Mirroring is configured at the repository level. You can create a new mirrored repository or convert an existing one.

1. Initializing the Mirror

1. Navigate to the + icon in the top right and select New Migration.
2. Select the source provider (e.g., GitHub, GitLab) or choose Git for a generic repository.
3. Enter the source repository URL.
4. If the repository is private, enter the credentials (Username and Personal Access Token).
5. Check the box This repository will be a mirror. This is the critical step; if omitted, Forgejo will perform a one-time import rather than a continuous sync.
6. Click Migrate Repository.

2. Configuring Sync Intervals

Once the repository is created, you must define how often Forgejo checks for updates.

1. Go to the repository Settings > Mirroring.
2. Under Mirror Settings, locate the Mirror Interval dropdown.
3. Select a frequency (e.g., every 8 hours, daily, or weekly).
4. Save the settings.

Authentication and Protocol Comparison

Choosing the right protocol impacts both security and reliability. Use the following table to decide:

Protocol	Auth Method	Best Use Case	Risk
HTTPS	Personal Access Token	Standard cloud-to-cloud sync	Token expiration
SSH	Deploy Keys	High-security internal servers	Key management overhead
Git	None (Public)	Public open-source mirrors	No write access

Verification and Diagnostics

After configuration, do not wait for the next scheduled interval to verify the setup.

Manual Connection Test

In Settings > Mirroring, click the Sync Now button. This triggers an immediate poll of the source repository. If the operation succeeds, the page will refresh with a success notification.

Checking the Mirror Logs

If the synchronization fails, check the logs to identify the failure point (e.g., 401 Unauthorized or 404 Not Found):

• Navigate to Settings > Actions > Mirroring logs.
• Look for the most recent timestamp.
• Verify that the ref updates (branches and tags) match the source repository's current state.

Handling Conflicts and History Rewrites

Forgejo mirroring is designed to reflect the source. However, specific git behaviors can cause issues:

• Force Pushes: If the source repository undergoes a git push --force, the mirror will attempt to update the local refs to match. This can lead to divergence if users have committed directly to the Forgejo mirror.
• Bidirectional Sync: While possible to configure mirrors on both ends, this is highly discouraged as it can create commit loops or duplicate commit hashes.

Rollback: Disabling the Mirror

If the mirror is causing instability or consuming too many resources, you can revert it to a standard repository:

1. Go to Settings > Mirroring.
2. Uncheck the This repository is a mirror option.
3. Save changes.

The repository will remain in its current state, but automatic polling will cease immediately.