English | 中文

sync-gitlab-gitea

This repository contains a small Bun script that synchronizes GitLab projects into a Gitea instance.

The script supports two main steps:

• Fetch GitLab projects and persist them to repos.json
• Import projects from repos.json into Gitea using the Gitea migration API

The entrypoint is sync-gitlab-gitea.ts.

Prerequisites

• bun runtime installed
• Access to a GitLab instance and a Gitea instance
• Personal access tokens for GitLab and Gitea

Environment variables

Required:

• GITLAB_TOKEN: GitLab personal access token with api scope
• GITEA_TOKEN: Gitea personal access token
• GITEA_REPO_OWNER: Target user or organization on Gitea that will own imported repositories

Optional:

• GITLAB_BASE_URL: GitLab base URL. Default: https://gitlab.com
• GITLAB_API_BASE: Override full GitLab API base URL (for example for self-hosted GitLab)
• GITLAB_PER_PAGE: GitLab pagination size. Default: 100
• GITLAB_MEMBERSHIP: Whether to limit projects to those the token user is a member of. Default: true
• GITLAB_CLONE_USERNAME: Username for HTTPS clone from GitLab. Default: oauth2
• GITEA_BASE_URL: Base URL of the Gitea instance. Default: http://localhost:3000
• SYNC_INTERVAL_SECONDS: Interval in seconds between each repository import. Default: 30
• SYNC_BATCH_SIZE: Maximum number of repositories to import in a single run. Default: 1

Modes

The script accepts a mode argument:

• fetch: Fetch projects from GitLab and write repos.json
• import: Read repos.json and import repositories into Gitea
• all: Run fetch and then import (default)

Usage

Show help:

bun run sync-gitlab-gitea.ts --help

Fetch repositories from GitLab:

GITLAB_TOKEN=... bun run sync-gitlab-gitea.ts fetch

Import repositories into Gitea (expects repos.json to exist):

GITLAB_TOKEN=...
GITEA_TOKEN=...
GITEA_REPO_OWNER=your-gitea-user-or-org
GITEA_BASE_URL=http://localhost:3000 \
  bun run sync-gitlab-gitea.ts import

Run both steps in one go:

GITLAB_TOKEN=...
GITEA_TOKEN=...
GITEA_REPO_OWNER=your-gitea-user-or-org
GITEA_BASE_URL=http://localhost:3000 \
  bun run sync-gitlab-gitea.ts

How it works

• fetchGitLabProjects queries the GitLab API (/projects) page by page and builds an in-memory list of repository metadata.
• The resulting list is stored in repos.json in the project root directory.
• importReposToGitea reads repos.json, filters repositories that are not yet imported, and calls the Gitea /api/v1/repos/migrate endpoint.
• Each successful import updates repos.json, including the Gitea repository owner and name.

The file repos.json is ignored by Git and is treated as local state.

sync-gitlab-gitea（中文版）

这个仓库包含一个使用 Bun 运行的小脚本，用于将 GitLab 上的项目同步到 Gitea 实例中。

脚本主要分为两个步骤：

• 从 GitLab 拉取项目列表，并保存到 repos.json
• 从 repos.json 中读取项目列表，并调用 Gitea 的迁移 API 进行导入

脚本入口文件为 sync-gitlab-gitea.ts。

前置条件

• 已安装 bun 运行时
• 可以访问一个 GitLab 实例和一个 Gitea 实例
• 拥有 GitLab 和 Gitea 的个人访问令牌

环境变量

必需：

• GITLAB_TOKEN：GitLab 个人访问令牌，需要具有 api 权限
• GITEA_TOKEN：Gitea 个人访问令牌
• GITEA_REPO_OWNER：在 Gitea 上用于接收导入仓库的目标用户或组织

可选：

• GITLAB_BASE_URL：GitLab 基础地址，默认 https://gitlab.com
• GITLAB_API_BASE：覆盖完整的 GitLab API 地址（适用于自建 GitLab）
• GITLAB_PER_PAGE：GitLab 分页大小，默认 100
• GITLAB_MEMBERSHIP：是否只拉取当前令牌用户参与的项目，默认 true
• GITLAB_CLONE_USERNAME：通过 HTTPS 从 GitLab 克隆时使用的用户名，默认 oauth2
• GITEA_BASE_URL：Gitea 实例的基础地址，默认 http://localhost:3000
• SYNC_INTERVAL_SECONDS：每次导入仓库之间的间隔秒数，默认 30
• SYNC_BATCH_SIZE：单次运行最多导入的仓库数量，默认 1

模式

脚本接受一个 mode 参数：

• fetch：从 GitLab 拉取项目列表并写入 repos.json
• import：从 repos.json 读取项目并导入到 Gitea
• all：先执行 fetch 再执行 import（默认）

使用示例

显示帮助：

bun run sync-gitlab-gitea.ts --help

仅从 GitLab 拉取仓库：

GITLAB_TOKEN=... bun run sync-gitlab-gitea.ts fetch

仅导入到 Gitea（需要事先存在 repos.json）：

GITLAB_TOKEN=...
GITEA_TOKEN=...
GITEA_REPO_OWNER=your-gitea-user-or-org
GITEA_BASE_URL=http://localhost:3000 \
  bun run sync-gitlab-gitea.ts import

一次性完成拉取和导入：

GITLAB_TOKEN=...
GITEA_TOKEN=...
GITEA_REPO_OWNER=your-gitea-user-or-org
GITEA_BASE_URL=http://localhost:3000 \
  bun run sync-gitlab-gitea.ts

工作原理

• fetchGitLabProjects 调用 GitLab 的 /projects API 分页拉取项目列表，并构建内存中的仓库元数据列表。
• 结果列表会写入项目根目录下的 repos.json。
• importReposToGitea 从 repos.json 中读取数据，过滤出尚未导入的仓库，并调用 Gitea 的 /api/v1/repos/migrate 接口。
• 每次导入成功后，会更新 repos.json 中对应仓库的导入状态，以及在 Gitea 上的仓库拥有者和仓库名。

repos.json 文件已经被 Git 忽略，仅作为本地状态文件使用。