Forgejo Tools

中文：Forgejo Tools 是一个面向个人和小团队的 Forgejo 自动化工具集合，提供 Web UI、单用户登录、SQLite 配置存储、仓库迁移和持续同步能力。它可以把 Gitea、GitHub、Forgejo、自定义 Gitea 兼容服务，以及通用 HTTP Git 仓库持续镜像到 Forgejo。

English: Forgejo Tools is a lightweight web-based automation suite for personal and small-team Forgejo workflows. It provides a Web UI, single-user login, SQLite-backed configuration, repository migration, and continuous Git sync from Gitea, GitHub, Forgejo, custom Gitea-compatible services, and generic HTTP Git remotes.

目录 / Contents

• 中文文档
• English Documentation

中文文档

功能

• 使用 SQLite 保存全局 Git 服务地址、API Token 和 Git 克隆用户名。
• 通过当前电脑作为中转，把选中的仓库迁移到 Forgejo。
• 创建提交定时检测器，周期性检查源仓库是否有新提交。
• 发现新提交后自动执行 mirror 同步到 Forgejo。
• 支持 Forgejo、Gitea、GitHub、自定义 Gitea 兼容服务。
• 支持通用 HTTP Git 服务，可直接填写完整 clone URL。
• 支持中文和英文界面。
• 支持 Docker Compose 部署。

本地启动

uv sync
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

打开：

http://127.0.0.1:8000

系统始终启用登录。默认账号：

admin / admin

部署前请修改账号密码：

$env:FORGEJO_TOOLS_USERNAME = "admin"
$env:FORGEJO_TOOLS_PASSWORD = "replace-this-password"
$env:FORGEJO_TOOLS_SECRET_KEY = "replace-this-with-a-long-random-secret"
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

界面支持中英文切换。可以点击顶部导航的语言按钮，也可以在 URL 后添加：

?lang=zh-CN
?lang=en

如果本机 uv 缓存目录有权限问题：

$env:UV_CACHE_DIR = "$PWD\.uv-cache"
$env:UV_PYTHON = "C:\Program Files\Python312\python.exe"
uv sync
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

全局服务配置

打开 服务配置 页面，添加一个或多个服务：

• Forgejo：目标 Forgejo 实例。
• Gitea：源或目标 Gitea 兼容实例。
• GitHub：源 GitHub 账号或组织。
• Custom Gitea-compatible：自建的 Gitea API 兼容服务。
• Generic Git HTTP service：任意可通过 HTTP clone 的 Git 服务。该类型不能自动列出仓库，但可在同步任务中填写完整 clone URL。

配置保存位置：

data/forgejo_tools.sqlite

该 SQLite 数据库不会提交到 Git。

Docker 部署

复制环境变量示例并修改密钥：

Copy-Item .env.example .env

启动服务：

docker compose up -d --build

打开：

http://127.0.0.1:8000

Compose 会持久化：

• SQLite 数据库：forgejo-tools-data
• Git mirror 工作缓存：forgejo-tools-work

必须配置的环境变量：

• FORGEJO_TOOLS_USERNAME
• FORGEJO_TOOLS_PASSWORD
• FORGEJO_TOOLS_SECRET_KEY

可选环境变量：

• FORGEJO_TOOLS_HOST，Docker 中默认 0.0.0.0
• FORGEJO_TOOLS_PORT，默认 8000

选择仓库迁移

打开 仓库迁移 页面，选择：

• 源服务
• 目标 Forgejo 服务
• 目标 Owner

加载仓库后勾选要迁移的仓库并启动迁移。

迁移使用当前电脑作为中转：

git clone --mirror <source>
git push --mirror <target>

该方式迁移 Git 分支和标签，不迁移 Issues、Pull Requests、Releases 等平台元数据。

提交定时检测器

打开 定时同步 页面并创建检测器：

• 源服务
• 源仓库，例如 owner/repo
• 如果是通用 Git 服务，源仓库可以填写完整 clone URL，例如 https://git.example.com/team/project.git
• 目标 Forgejo 服务
• 目标 Owner 和目标仓库名
• 检测间隔秒数

后台调度器会定期检查最新提交。发现新提交后，会自动把源仓库 mirror 到 Forgejo。

注意事项

• 运行服务的终端窗口需要保持打开。
• 当前电脑或容器中必须安装 Git。
• 源服务 Token 需要读取仓库权限。
• 目标 Forgejo Token 需要创建仓库和推送代码权限。
• Docker 部署时请务必修改默认账号密码和 FORGEJO_TOOLS_SECRET_KEY。

English Documentation

Features

• Store global Git service URLs, API tokens, and Git clone usernames in SQLite.
• Migrate selected repositories into Forgejo through the current machine as a relay.
• Create scheduled commit detectors that periodically check source repositories for new commits.
• Automatically mirror changed repositories into Forgejo.
• Support Forgejo, Gitea, GitHub, and custom Gitea-compatible services.
• Support generic HTTP Git services with full clone URLs.
• Support English and Simplified Chinese UI.
• Support Docker Compose deployment.

Local Start

uv sync
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

Open:

http://127.0.0.1:8000

Login is always enabled. The default account is:

admin / admin

Change it before deployment:

$env:FORGEJO_TOOLS_USERNAME = "admin"
$env:FORGEJO_TOOLS_PASSWORD = "replace-this-password"
$env:FORGEJO_TOOLS_SECRET_KEY = "replace-this-with-a-long-random-secret"
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

The UI supports English and Simplified Chinese. Use the language link in the top navigation or add one of these query parameters:

?lang=zh-CN
?lang=en

If the local uv cache has permission issues:

$env:UV_CACHE_DIR = "$PWD\.uv-cache"
$env:UV_PYTHON = "C:\Program Files\Python312\python.exe"
uv sync
powershell -ExecutionPolicy Bypass -File .\scripts\start_server.ps1

Global Services

Open Services and add one or more services:

• Forgejo: target Forgejo instance.
• Gitea: source or target Gitea-compatible instance.
• GitHub: source GitHub account or organization.
• Custom Gitea-compatible: self-hosted service with Gitea-compatible APIs.
• Generic Git HTTP service: any Git service reachable through HTTP clone URLs. Repository listing is not available for this type, but sync jobs can use a full clone URL.

Settings are saved in:

data/forgejo_tools.sqlite

The SQLite database is ignored by Git.

Docker Deployment

Copy the example environment file and change all secrets:

Copy-Item .env.example .env

Start the service:

docker compose up -d --build

Open:

http://127.0.0.1:8000

The compose file persists:

• SQLite database: forgejo-tools-data
• Git mirror work cache: forgejo-tools-work

Required environment variables:

• FORGEJO_TOOLS_USERNAME
• FORGEJO_TOOLS_PASSWORD
• FORGEJO_TOOLS_SECRET_KEY

Optional environment variables:

• FORGEJO_TOOLS_HOST, defaults to 0.0.0.0 in Docker
• FORGEJO_TOOLS_PORT, defaults to 8000

Selected Migration

Open Migrate, choose:

• Source service
• Target Forgejo service
• Target owner

Then select repositories and start migration.

Migration uses the current machine as a relay:

git clone --mirror <source>
git push --mirror <target>

This migrates Git branches and tags. It does not migrate Issues, Pull Requests, Releases, or other platform metadata.

Commit Sync Detector

Open Sync Jobs and create a detector:

• Source service
• Source repo, for example owner/repo
• For Generic Git services, Source repo can be a full clone URL such as https://git.example.com/team/project.git
• Target Forgejo service
• Target owner and target repo
• Interval seconds

The background scheduler checks for new commits. When a new commit is detected, it mirrors the repository into Forgejo.

Notes

• The terminal running the server must stay open.
• Git must be installed on the current machine or container.
• Source tokens need read access.
• Target Forgejo tokens need repository creation and push permissions.
• For Docker deployment, always change the default account and FORGEJO_TOOLS_SECRET_KEY.