---
name: gitea-repo-sync
description: 在自建或托管 Gitea 上自动创建仓库、初始化或复用本地 Git 项目、配置远程并安全推送分支/标签。适用于“给当前目录建 Gitea 仓库”“同步本地项目到 Gitea”“给组织创建仓库再推送代码”这类请求。
metadata:
  short-description: Create Gitea repositories and sync local projects safely
---
# Gitea Repo Sync

在 Gitea 上建仓、连远程、推送代码的标准化技能。

优先使用打包好的 `scripts/gitea_repo_sync.py`，不要重复手写零散 `curl` + `git` 命令。脚本会先探测仓库是否已存在，再按需要创建仓库、初始化本地 Git、配置远程并执行 push。

## 什么时候用

- 用户要把当前目录项目同步到 Gitea
- 用户要在某个 owner 或 organization 下创建新仓库
- 本地目录还不是 Git 仓库，但需要初始化后推送
- 需要复用已有远程仓库，而不是盲目重复创建
- 需要在自动化里稳定处理 token、remote 和 push 顺序

## 需要的输入

- `GITEA_URL`：例如 `https://git.hk.hao.work`
- `GITEA_TOKEN`：具备建仓和推送权限的 token
- `owner`：用户名或组织名，例如 `hao`
- `repo`：仓库名，例如 `demo-project`
- `source_dir`：要同步的本地目录
- 可选 `branch`：默认推送的分支名，常见为 `main`
- 可选 `description` / `private` / `tags`

优先使用环境变量：

```bash
export GITEA_URL='https://git.hk.hao.work'
export GITEA_TOKEN='<your_token>'
```

## 标准流程

1. 先确认本地目录路径、目标 owner 和 repo 名。
2. 调 Gitea API 查询仓库是否已存在。
3. 若不存在，则按 owner 类型创建：
   - 当前登录用户自己的仓库：`POST /api/v1/user/repos`
   - 组织仓库：`POST /api/v1/orgs/{org}/repos`
4. 进入本地目录检查是否为 Git 仓库：
   - 不是 Git 仓库时，只有在明确需要时才初始化
   - 已经是 Git 仓库时，优先复用现有提交历史
5. 配置或校验远程：
   - 无 remote 时新增
   - remote 已存在但 URL 不同，默认停止并提示；只有明确允许时才替换
6. 按请求推送：
   - 单分支：`push --set-upstream`
   - 全部分支：`push --all`
   - 标签：`push --tags`
7. 输出最终仓库 URL、remote URL、本地分支和 push 结果。

## 安全默认值

- 不强制覆盖现有 remote，除非明确传 `--replace-remote`
- 不自动 `git add` / `git commit`，除非明确传 `--stage-all` 和 `--commit-message`
- 不自动 `force push`
- 不把 token 写进 git remote URL
- 仓库已存在时优先复用，不重复创建

## 推荐脚本

使用 `scripts/gitea_repo_sync.py`。

### 常见用法

```bash
python3 scripts/gitea_repo_sync.py \
  --server-url "$GITEA_URL" \
  --token "$GITEA_TOKEN" \
  --owner hao \
  --repo demo-project \
  --source-dir /path/to/project \
  --init-git \
  --branch main \
  --stage-all \
  --commit-message 'Initial import'
```

如果仓库已存在，只同步当前分支：

```bash
python3 scripts/gitea_repo_sync.py \
  --server-url "$GITEA_URL" \
  --token "$GITEA_TOKEN" \
  --owner hao \
  --repo demo-project \
  --source-dir /path/to/project \
  --branch main
```

推送全部分支和标签：

```bash
python3 scripts/gitea_repo_sync.py \
  --server-url "$GITEA_URL" \
  --token "$GITEA_TOKEN" \
  --owner hao \
  --repo demo-project \
  --source-dir /path/to/project \
  --push-all \
  --tags
```

## 常见坑

- 不要把 `GITEA_TOKEN` 提交进仓库。
- 不要在 remote URL 里长期保存带 token 的认证串。
- 不要在 remote 已存在时静默改写 URL。
- 不要在工作区有未确认修改时自动提交；先确认是否需要 `--stage-all`。
- 不要默认 `--push-all`；很多场景只需要当前分支。

## 参考资料

- `references/gitea-api-notes.md`