skills/gitea-repo-sync/SKILL.md

name, description, metadata

name	description	metadata
gitea-repo-sync	在自建或托管 Gitea 上自动创建仓库、初始化或复用本地 Git 项目、配置远程并安全推送分支/标签。适用于“给当前目录建 Gitea 仓库”“同步本地项目到 Gitea”“给组织创建仓库再推送代码”这类请求。	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

优先使用环境变量：

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。

常见用法

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'

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

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

推送全部分支和标签：

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