Configure Pull Mirroring in a Forgejo Repository

Desired Outcome

Enable pull mirroring so that a Forgejo repository automatically fetches and updates all branches and tags from an upstream Git remote on a regular interval.

Prerequisites

• Forgejo account with Owner or Admin rights on the target repository.
• Network connectivity from the Forgejo server host to the upstream Git server (HTTP(S) or SSH).
• Instance‑level mirroring not disabled by the Forgejo administrator (check Settings → Administration → Repository → Mirroring if you have admin access).
• Forgejo version 1.8 or later (menu paths and interval limits are stable in this range).

Procedure

1. Navigate to the repository you want to mirror, then click Settings → Mirroring in the sidebar.
2. Toggle Enable mirroring to ON.
3. Set Mirror direction to Pull only (this ensures Forgejo only receives changes from the upstream).
4. Enter the upstream Git URL in the Git remote URL field, e.g. https://github.com/example/upstream.git or [contact removed]:example/upstream.git.
5. If the upstream requires authentication:
   • For HTTPS: provide a username and personal access token or password in the Username and Password/PAT fields.
   • For SSH: upload a deploy key pair via Settings → SSH / GPG keys and ensure the Forgejo server can use the private key (no passphrase recommended for automation).
6. Set the Mirror interval (e.g., 5 minutes). This is a best‑effort schedule; the actual run may be delayed by worker load or network latency.
7. Click Save settings.
8. Optionally trigger an immediate sync by clicking Mirror now (appears after saving). Wait a few moments for the worker to finish.

Expected Checks

• On the Mirroring page, the status should show Active with a recent Last sync timestamp.
• Visit the repository’s Branches and Tags tabs; upstream refs should appear identical to those in the upstream.
• Verify a specific commit: run git ls-remote refs/heads/ upstream and compare the hash with git rev-parse origin/ inside a clone of the Forgejo repo (or use the Forgejo UI commit view).
• Check that the mirror worker logs (accessible via Administration → System → Logs if you are an instance admin) contain no error lines for the repository.

Recovery Options

• Disable and re‑enable: Turn mirroring off, wait a minute, then turn it back on to reset the worker state.
• Clear stuck tasks: In the instance administration area (Site Administration → Monitor → Queue or similar), locate any failed mirror jobs for the repository and retry or delete them.
• Manual sync: On a local clone, run git fetch followed by git push --mirror to force the state, then re‑enable mirroring.
• Log inspection: Review Forgejo server logs for messages like mirroring worker failed, authentication errors, or network timeouts. Address the underlying issue (credentials, firewall, DNS) before retrying.

Limitations and Considerations

• Pull mirroring will overwrite local Forgejo refs to match the upstream; any direct pushes to mirrored branches may be discarded on the next sync.
• Credentials stored in the repository settings are visible to instance administrators and users with repository‑settings access. Prefer SSH deploy keys or scoped personal access tokens with limited permissions.
• The mirror interval is best‑effort; large repositories or high latency can cause updates to lag beyond the configured window.
• Mirroring an untrusted upstream can introduce malicious tags or branches. Inspect upstream refs before enabling mirroring on a production instance.
• Very large repositories may exceed the default worker timeout; adjust the worker configuration or increase the timeout if necessary (requires instance admin access).