Configuring Pull Mirroring in Forgejo to Synchronize External Git Repositories

The Problem: Manual Repository Syncing

Maintaining a local copy of an external repository—such as one hosted on GitHub or GitLab—often involves tedious manual cloning and fetching. When these external repositories serve as upstream sources for a local development team, keeping the local instance updated is critical for avoiding merge conflicts and ensuring the latest security patches are present.

The solution is Pull Mirroring. This Forgejo feature automates the process of fetching all branches, tags, and commit history from a remote source at a defined interval, transforming a local repository into a read-only or editable mirror of the original.

Prerequisites

• A running Forgejo instance (version 6.0 or later recommended).
• Administrative or Owner permissions for the target organization or user account in Forgejo.
• A valid access method for the source repository: either a Personal Access Token (HTTPS) or a Deploy Key (SSH).
• The Forgejo system user must have outbound network access to the remote Git provider.

Implementing a Pull Mirror

Pull mirroring is configured at the repository level. You can either create a new mirror or convert an existing repository into one.

Step 1: Create the Mirror Repository

1. Click 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 URL.
3. Enter the remote repository URL.
4. Check the box labeled This repository will be a mirror. This is the critical step that enables the automated synchronization logic.
5. Provide the necessary authentication credentials (Token or SSH key) if the source repository is private.
6. Click Migrate Repository.

Step 2: Configure Synchronization Intervals

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

1. Navigate to the repository Settings.
2. Select Mirroring from the left-hand sidebar.
3. Under the Mirror Settings section, locate the Mirror Interval dropdown.
4. Select an interval (e.g., every 8 hours). Avoid selecting the shortest intervals for very large repositories to prevent timeouts or rate-limiting from the source provider.
5. Click Save.

Comparison: HTTPS vs. SSH Authentication

Choosing the right authentication method affects how you manage credentials and how the server interacts with the remote.

Feature	HTTPS (Token)	SSH (Deploy Key)
Setup Ease	High (Paste token)	Medium (Generate/Upload key)
Scope	User-based (wide access)	Repo-based (restricted access)
Security	Token can be revoked	Key is tied to specific repo
Reliability	Subject to HTTPS timeouts	Generally more stable for large clones

Verification and Diagnostics

After configuration, verify that the mirror is functioning as expected using these three checks:

1. Sync Status Check

Go to Settings > Mirroring. Look for the Last Sync timestamp. If the sync failed, Forgejo will display a red error message indicating the reason (e.g., Authentication failed or Connection timed out).

2. Commit Hash Validation

Run the following command on your local machine to compare the HEAD of the remote source and the Forgejo mirror:

# Check source hash
git ls-remote https://github.com/user/repo.git HEAD

# Check Forgejo mirror hash
git ls-remote https://forgejo.local/user/repo.git HEAD

The hexadecimal hashes must match exactly for the mirror to be considered current.

3. Log Inspection

If the mirror is not updating, check the Forgejo server logs. Look for git fetch entries. If you see 429 Too Many Requests, increase your Mirror Interval to avoid being banned by the source provider.

Limitations and Recovery

Limitations: Pull mirroring only synchronizes Git data (commits, branches, tags). It does not synchronize platform-specific metadata such as Issues, Pull Requests, or Wiki pages from the source provider. These must be migrated manually or via API scripts.

Rollback: Disabling the Mirror

If the mirror is causing performance degradation or synchronization loops:

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

This converts the repository into a standard local repository. All existing data remains, but automated updates will cease immediately.