Enrich all GitHub pull mirrors on your own Gitea instance with repository metadata, topics, issues and comments that native Git mirroring does not synchronize.

The script discovers repositories automatically and derives each GitHub source from the mirror URL. Source and destination repository names can differ.

Features

Automatic discovery, including private mirrors visible to the Gitea token.
Description, website, default branch and topic synchronization.
Issue titles, bodies, open/closed states and comment synchronization.
Existing synchronization markers prevent duplicate imports on repeated runs.
Foreground preview, foreground apply and quiet background apply modes.
GitHub rate-limit diagnostics, bounded waits and account-level stop conditions.
Repository isolation, a shared process lock and per-repository summaries.
Optional native Gitea mirror-sync requests.

Requirements

Linux, Bash 4.3+, jq 1.6+, curl 7.55+, util-linux and coreutils.

On Debian/Ubuntu:

sudo apt-get install bash curl jq util-linux coreutils

Configuration

Use gitea-github-sync.conf.example as the template for /etc/gitea-github-sync.conf. Update an existing configuration rather than overwriting its tokens. Set your Gitea URL and token, the account owner, and a GitHub token where needed. An empty GITEA_OWNER selects the token's account.

Set GITEA_URL to your own Gitea instance in the configuration:

GITEA_URL='https://gitea.example.com'
GITEA_OWNER=''

Replace the example address with your server's URL. For an installation under a subdirectory, use e.g. GITEA_URL='https://example.com/gitea'. Do not append /api/v1. There is no built-in Gitea server address; an absent or empty GITEA_URL stops the script before any API request. GITEA_OWNER may be left empty to detect the authenticated account, or set to an owner to scan.

Restrict the configuration to its owner:

sudo chmod 600 /etc/gitea-github-sync.conf

Never commit the populated configuration or tokens to this repository.

Usage

# Preview without API writes (the default)
sudo bash ./gitea-github-sync.sh --dry-run

# Synchronize in the foreground
sudo bash ./gitea-github-sync.sh --apply

# Synchronize in the background without terminal output
sudo bash ./gitea-github-sync.sh --apply-quiet

# Enrich mirrors without queuing native Git synchronization
sudo bash ./gitea-github-sync.sh --apply --no-git

Use --config FILE for another configuration file and --help for all options. Choose only one execution mode.

Quiet mode appends progress and errors to /var/log/gitea-github-sync.log, configurable through QUIET_LOG_FILE. Its launcher returns immediately; check the log's final exit_status to determine the actual result.

sudo tail -f /var/log/gitea-github-sync.log

Weekly cron job

The release includes gitea-github-sync.cron, which runs the script as root every Monday at 03:00 in the server's timezone. First configure /etc/gitea-github-sync.conf with your instance URL and tokens. From the extracted release directory, install the script and cron entry:

sudo install -o root -g root -m 755 ./gitea-github-sync.sh /usr/local/bin/gitea-github-sync.sh
sudo install -o root -g root -m 644 ./gitea-github-sync.cron /etc/cron.d/gitea-github-sync

This does not overwrite your configuration or trigger an immediate sync. Check for an existing equivalent job before installing, so it is not scheduled twice. This file is for /etc/cron.d, where the root column is required; do not paste it unchanged into a per-user crontab -e.

sudo cat /etc/cron.d/gitea-github-sync
systemctl is-active cron
systemctl is-enabled cron
timedatectl show -p Timezone
sudo tail -n 100 /var/log/gitea-github-sync.log

Cron must be installed and running. On a system with an existing active cron service, a new /etc/cron.d file is read automatically without a restart. The log path can be overridden by QUIET_LOG_FILE. Look for Background worker finished: PID=..., exit_status=0 to confirm successful completion. Starting the quiet worker alone does not confirm completion. If using a scheduler that must track the final process exit code, use foreground --apply instead. No additional shell output redirection is needed for quiet mode.

See the changelog for what changed and why. Quiet mode already existed in v1.0.1; v1.0.2 adds the reusable scheduling setup and documentation.

Depending on the number of repositories/mirrors and their issues/comments, execution can take a very long time, potentially hours. Quiet mode does not speed up synchronization. GitHub limits may require a later run.

YunoHost deployment

The original deployment uses Gitea installed through YunoHost. YunoHost manages its own installation and data directories; repository storage paths can differ from standalone Gitea examples. This script uses HTTP APIs and does not require local repository paths. Include any web path prefix in GITEA_URL.

See the full English guide for locating the effective configuration, YunoHost path details, all settings, all Bash functions and troubleshooting.

Scope and limitations

Pull requests, releases/assets, labels, milestones, reactions, assignments, original authorship and timestamps are not copied. Source deletions do not delete Gitea records. Unmarked local records are untouched; previous imports without markers require separate mapping. Local edits to synchronized fields are replaced by the GitHub source. Disabled internal issue trackers receive metadata updates only. Native mirror-sync runs asynchronously in Gitea.

The script has been checked with Bash syntax validation, ShellCheck and local mock API tests, including multiple mirrors, idempotency, throttling and quiet mode.

Downloads

Download the script or the complete bundle from GitHub Releases. The latest release is v1.0.2, with weekly root cron setup and deployment notes.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-only). See LICENSE for the full license text.