skills/gitea-repo-sync/references/gitea-api-notes.md

Gitea API Notes

本技能默认对接 Gitea v1.25.x，核心只依赖少量稳定接口：

• GET /api/v1/user
• GET /api/v1/repos/{owner}/{repo}
• POST /api/v1/user/repos
• POST /api/v1/orgs/{org}/repos

创建仓库的 owner 选择

1. 先调用 GET /api/v1/user 获取当前 token 对应登录名。
2. 如果目标 owner 与当前登录名一致，走 POST /api/v1/user/repos。
3. 如果目标 owner 不同，按组织仓库处理，走 POST /api/v1/orgs/{org}/repos。

推荐请求头

Authorization: token <token>
Content-Type: application/json
Accept: application/json

Git Push 认证建议

不要把 token 写入 git remote -v。

优先使用一次性的 HTTP header：

• 用户名：Gitea 登录名
• 密码：token
• Header：Authorization: Basic <base64(username:token)>

这样可以在 push 时认证，但不会把 token 持久化到仓库配置里。

建议的环境变量

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

失败时优先检查

• token 是否有 repo 创建/写入权限
• owner 是用户还是组织
• 本地目录是否已经是 Git 仓库
• 当前分支是否存在提交
• 远程 URL 是否已指向别的仓库