agent-skills/devops/gitea-code-sync/references/gitea-api.md

Gitea API 参考

认证

# 从 ~/.netrc 获取 token
TOKEN=$(grep gitea.ephron.ren -A1 ~/.netrc | grep password | awk '{print $2}')

# 方式1: Basic auth (token as password) — 推荐
-u "token:$TOKEN"

# 方式2: Token header
-H "Authorization: token $TOKEN"

仓库操作

搜索仓库

GET /api/v1/repos/search?limit=10&sort=updated

获取仓库信息

GET /api/v1/repos/{owner}/{repo}

创建仓库

POST /api/v1/user/repos
{
  "name": "repo_name",
  "description": "描述",
  "private": false,
  "auto_init": true,
  "default_branch": "main"
}

修改仓库设置

PATCH /api/v1/repos/{owner}/{repo}
{
  "private": true,           # 修改可见性
  "description": "新描述",    # 修改描述
  "default_branch": "main"   # 修改默认分支
}

删除仓库

DELETE /api/v1/repos/{owner}/{repo}

协作者管理

获取协作者列表

GET /api/v1/repos/{owner}/{repo}/collaborators

添加协作者

PUT /api/v1/repos/{owner}/{repo}/collaborators/{username}
{
  "permission": "write"  # read, write, admin
}

删除协作者

DELETE /api/v1/repos/{owner}/{repo}/collaborators/{username}

修改协作者权限

PATCH /api/v1/repos/{owner}/{repo}/collaborators/{username}
{
  "permission": "admin"
}

分支操作

获取分支列表

GET /api/v1/repos/{owner}/{repo}/branches

创建分支

POST /api/v1/repos/{owner}/{repo}/branches
{
  "new_branch_name": "feature-branch",
  "old_branch_name": "main"
}

文件操作

获取文件内容

GET /api/v1/repos/{owner}/{repo}/contents/{filepath}

创建/更新文件

POST /api/v1/repos/{owner}/{repo}/contents/{filepath}
{
  "message": "commit message",
  "content": "base64_encoded_content",
  "branch": "main"
}

删除文件

DELETE /api/v1/repos/{owner}/{repo}/contents/{filepath}
{
  "message": "delete message",
  "sha": "file_sha"
}

Release 操作

获取 Release 列表

GET /api/v1/repos/{owner}/{repo}/releases

创建 Release

POST /api/v1/repos/{owner}/{repo}/releases
{
  "tag_name": "v1.0.0",
  "name": "Release 1.0.0",
  "body": "Release notes",
  "draft": false,
  "prerelease": false
}

常用查询参数

参数	说明	示例
limit	返回数量	?limit=10
page	分页	?page=2
sort	排序字段	?sort=updated
order	排序方向	?order=desc
q	搜索关键词	?q=keyword

响应格式

成功响应通常返回 JSON 对象或数组。错误响应：

{
  "message": "error description",
  "url": "https://gitea.ephron.ren/api/swagger"
}

Token 权限

• read: 只读访问
• write: 读写访问
• admin: 完全管理权限

当前环境

• 平台: https://gitea.ephron.ren
• Agent 用户: Elaina (token in ~/.netrc)
• 主用户: ephron_ren