mirror of
https://github.com/adamzend/gitea-github-sync.git
synced 2026-10-31 03:11:58 +01:00
116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# Gitea GitHub Sync
|
|
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo chmod 600 /etc/gitea-github-sync.conf
|
|
```
|
|
|
|
Never commit the populated configuration or tokens to this repository.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
sudo tail -f /var/log/gitea-github-sync.log
|
|
```
|
|
|
|
**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](README.txt) 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](https://github.com/adamzend/gitea-github-sync/releases).
|
|
The latest release is **v1.0.1**, which requires an explicitly configured Gitea URL.
|