104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# Gitea Mirror
|
|
|
|
[](https://codecov.io/gh/AlekseyLobanov/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](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.
|
|
```bash
|
|
python gitea-mirror.py --config config.toml
|
|
```
|
|
|
|
|
|
### Docker
|
|
The simplest way.
|
|
|
|
**TBD**
|
|
|
|
## How to develop
|
|
We use [pre-commit](https://pre-commit.com/) for basic
|
|
style fixes and checks.
|
|
|
|
Install the development environment with:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
To run tests:
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
To run all checks:
|
|
```bash
|
|
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.
|