Gitea Mirror

Key idea for this project is to provide the simplest solution to backup all Gitea repositories on daily basis with simple command

How to use

This application requires only API key for Gitea. Unfortunately it only allows to create root-level API keys.

You can generate one here:

https://YOUR_INSTANCE/user/settings/applications

Other methods are not supporting:

1. User/password is not safe and hard to use with 2FA enabled
2. With ssh only public repositories may be found. Which is acceptable for full account mirroring.

Security notice. This application can use SSH or HTTP(S) as git transport layer. With SSH, you need to save git server ssh digest (~/.ssh/known_hosts file). To do this you just need to clone any repository over ssh first. With HTTP(S), credentials are passed to git through environment-based configuration and are not written into repository remote URLs.

Config. We use single config for this application. It is slightly ancient solution for modern Docker/Kubernetes backends, but provides configuration in one place and secure enough place to save token.

Example config is available in config.example.toml. Use main.api_token for Gitea API access. Use fetch.ssh_key for SSH cloning, or fetch.user and fetch.token for HTTP(S) cloning.

Repositories are stored as bare mirror clones. On the first run the tool uses git clone --mirror <url> <path>, and on following runs it updates each mirror with git remote update --prune. This mirrors all refs and handles forced updates from the server side, but the resulting directories are not working tree checkouts.

Native

Not recommended, but more efficient in space and does not require docker. removing the ability to specify a user

1. Clone this repository (git clone ...)
2. Install dependencies (pip3 install -r requirements.txt). Venv-level is recommended.
3. Install git (sudo apt install git)
4. And run it with path to TOML config.

python gitea-mirror.py --config config.toml

Docker

The simplest way.

TBD

How to develop

We use pre-commit for basic style fixes and checks.

Install the development environment with:

uv sync

To run tests:

make test

To run all checks:

make check

FAQ

• Q: Is it possible to specify user?

• A: This tool should be as simple as possible. Token as the only one identifier is good enough for 95% cases.

• Q: Why I can not just use gitea own backup command?

• A: For many personal instances or instances for small commands only repositories are important (not users, wiki, issues, etc). It does not solve backup problem in general, but gives possibility to back up all personal repositories with ease. (And without access to root-level of Gitea instance)

• Q: Why Python with dependencies for so small application?

• A: Using libraries for specific cases is a good practice in industry. And it keeps code simple and easy to verify (for bugs or malicious actions). Which is much more important than one-time venv or Docker setup.