Configure a Forgejo Pull Mirror to Track an Upstream Git Repository

Problem and takeaway

You need a Forgejo repository to stay current with an upstream Git project, but someone has to remember to run git fetch and push changes manually. Missed fetches leave CI pipelines, issue trackers, or internal forks working from stale code.

Forgejo includes a built-in pull mirror that automatically fetches branches and tags from an upstream remote on a schedule you choose. Once configured, Forgejo handles the repeated network calls so your repository reflects upstream changes without manual intervention.

Prerequisites

• A Forgejo repository where you have Owner or Admin rights.
• The upstream repository's clone URL, for example https://github.com/owner/upstream-repo.git or an SSH URL such as [contact removed]:owner/upstream-repo.git.
• Outbound network access from the Forgejo server to the upstream host.
• If the upstream is private, read-only credentials: a personal access token or deploy token for HTTPS, or an SSH key registered with the upstream host and uploaded to Forgejo.

A mirror updates remote-tracking references in Forgejo; it does not automatically merge fetched commits into your local default branch. If your workflow requires local changes, plan to merge or rebase after the mirror runs.

Configure the pull mirror

1. Open your repository in Forgejo and select Settings.
2. In the repository settings menu, choose Mirror.
3. Select Pull mirror, then enter the upstream remote URL.
4. Set the Sync interval. A conservative starting value is 60 minutes. Shorter intervals increase load on Forgejo and the upstream server and can trigger rate limiting.
5. Supply credentials if the upstream requires authentication. For HTTPS, enter the username and token. For SSH, confirm the private key exists in your Forgejo account settings and the corresponding public key is authorized on the upstream host.
6. Save the mirror configuration.
7. Click the manual sync button to start the initial transfer immediately rather than waiting for the first scheduled interval.

Example configuration

Upstream URL: https://github.com/example-org/example-project.git
Sync interval: 60 minutes
Authentication: username + personal access token (read-only, public repositories)

Replace the URL and credentials with values for your own upstream. Do not paste a personal password into the mirror form; use a token with repository read scope only.

Verify the mirror is working

• Open the repository Mirror settings page and confirm the Last updated timestamp changes after a manual sync.
• Compare the latest commit hash on Forgejo's default branch with the upstream default branch. In Forgejo, open the repository commit list; upstream, open the equivalent branch page.
• Run a local reference check from a workstation with Git installed:

git ls-remote https://github.com/example-org/example-project.git HEAD

Run this command locally, not on the Forgejo server unless you have shell access there. You need only network access and the git command. Expected output is a commit hash followed by HEAD. If the command fails, the upstream URL or network path is likely the problem, not Forgejo itself.

• Check Forgejo system or repository logs after a manual sync for mirror-service entries and any authentication or timeout errors.

Recovery when sync fails

Symptom	Check	Action
Mirror never updates	Last updated timestamp on Mirror page	Disable the mirror, verify the upstream URL and credentials, then re-enable and run a manual sync.
401 or 403 errors	Forgejo logs	Rotate or re-enter the access token; confirm it has not expired and still grants read access.
Network timeout	git ls-remote from the Forgejo host or a host on the same network	Review outbound firewall rules, proxy settings, and upstream availability.

To remove a mirror that is misconfigured, open Settings > Mirror and delete the mirror entry. This removes the scheduled sync and stored remote configuration; it does not delete branches or tags already fetched into the Forgejo repository.

Limitations

• Mirror interval granularity and available credential types vary by Forgejo release. Confirm the options shown in your instance before relying on a specific schedule.
• Fetching is not merging. Mirrored refs appear as remote-tracking references; local branches do not move automatically.
• Avoid very short intervals on public hosts such as GitHub or GitLab to reduce the risk of rate limiting.

Practical result check

Make a test commit to the upstream default branch, wait for the next mirror interval or trigger a manual sync, then open Forgejo and confirm the new commit appears in the repository commit list. If it does not, inspect the Mirror page timestamp and Forgejo logs before changing credentials.