Setting Up Repository Mirroring in Forgejo: A Decision Guide

The Decision at Hand

You manage a Forgejo instance and need a repository to reflect changes from an upstream source. Perhaps you're onboarding a downstream team, preserving a backup, or feeding a CI pipeline. Whatever the reason, Forgejo offers repository-level mirroring, but it does not mirror an entire organization or project tree from a single setting. Each repository must define its own mirror.

Constraints You're Working With

• Per-repository only: Mirror definitions apply to individual repositories; there is no org-wide mirror trigger.
• Sync interval: The default is every 8 hours, but you can adjust it from 1 minute to 24 hours.
• Protocol support: Mirrors can target HTTP, SSH, or Git protocol URLs.
• Authentication: If the target requires credentials, store them in the site-wide TOML config or use SSH keys; plain-text passwords are discouraged.

Supported Options at a Glance

Trade-Offs to Consider

Choosing between the web UI and TOML config depends on your automation needs. The UI is quick for one-off setups, but changes are not version-controlled and disappear if the repository is recreated. The TOML approach lets you mirror many repositories through a single config file, which is useful when you provision repos programmatically or want the configuration tracked in version control. However, TOML changes require a Forgejo restart or config reload, and mis-formatted entries can prevent the server from starting.

Concrete Implementation

Adding a Mirror via TOML Configuration

Forgejo reads a site-wide TOML file for mirror definitions. Place the following section in custom/conf/app.ini (or the config path your distribution uses) and replace the placeholders with your actual values.

[mirror "my/repo"]
  enabled = true
  interval = "1h"
  url = "https://upstream.example.com/my/repo.git"
  [mirror.auth]
  username = "mirror-user"
  password = "very-secret"

Key points:

• enabled toggles the mirror on or off.
• interval accepts a Go duration string (e.g., "30m", "24h", "1s"). The research brief notes the practical range of 1 minute to 24 hours.
• url must point to a valid remote that Forgejo can reach from the server's network context.
• The [mirror.auth] block is optional; if the remote uses SSH, place the URL in the form [contact removed]:owner/repo and ensure the Forgejo service account has the corresponding private key mounted.

Verification

1. After saving the config file, restart Forgejo (or send a SIGHUP if your deployment supports hot reload) so the new mirror definition is picked up.
2. Navigate to the repository in the web UI, open the Mirror tab. The Mirror enabled toggle should show true and the Last sync timestamp should update within the interval you set.
3. Check the Forgejo log file (typically data/log after startup) for entries containing mirror sync. A successful attempt logs something like Mirror sync completed for my/repo; failures include the error reason and may reference mirror_timeout.
4. If the sync does not appear within the configured interval, verify network reachability, confirm that the URL format is correct, and check that any required SSH keys are present in data/ssh or mounted appropriately.

Known Limitations

• Forgejo does not support mirroring an entire organization or tree of repositories; each repo requires its own [mirror] section or UI setup.
• Very large repositories with many refs can cause sync failures or timeouts. If a sync hangs, increase the mirror_timeout setting in the TOML config or consider narrowing the mirror scope (e.g., mirror only default branch).
• Authentication to the mirror target must be handled securely. Storing plain-text passwords in TOML is supported but not recommended for production; prefer SSH key authentication or secret-management integrations.

Practical Takeaway

If you need a single repository to stay in sync with an upstream host, use the web UI for a quick one-time setup, or add a [mirror] section to Forgejo's TOML config for reproducible, version-controlled mirror definitions. Set the sync interval to balance freshness against server load—1h is a common starting point—and always validate the mirror via the Mirror tab and server logs after the first sync cycle.