120 行
3.8 KiB
Markdown
120 行
3.8 KiB
Markdown
---
|
|
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`
|