first commit

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

@@ -0,0 +1,170 @@
+# Gitea API 参考
+
+## 认证
+```bash
+# 从 ~/.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"
+```
+
+## 仓库操作
+
+### 搜索仓库
+```bash
+GET /api/v1/repos/search?limit=10&sort=updated
+```
+
+### 获取仓库信息
+```bash
+GET /api/v1/repos/{owner}/{repo}
+```
+
+### 创建仓库
+```bash
+POST /api/v1/user/repos
+{
+  "name": "repo_name",
+  "description": "描述",
+  "private": false,
+  "auto_init": true,
+  "default_branch": "main"
+}
+```
+
+### 修改仓库设置
+```bash
+PATCH /api/v1/repos/{owner}/{repo}
+{
+  "private": true,           # 修改可见性
+  "description": "新描述",    # 修改描述
+  "default_branch": "main"   # 修改默认分支
+}
+```
+
+### 删除仓库
+```bash
+DELETE /api/v1/repos/{owner}/{repo}
+```
+
+## 协作者管理
+
+### 获取协作者列表
+```bash
+GET /api/v1/repos/{owner}/{repo}/collaborators
+```
+
+### 添加协作者
+```bash
+PUT /api/v1/repos/{owner}/{repo}/collaborators/{username}
+{
+  "permission": "write"  # read, write, admin
+}
+```
+
+### 删除协作者
+```bash
+DELETE /api/v1/repos/{owner}/{repo}/collaborators/{username}
+```
+
+### 修改协作者权限
+```bash
+PATCH /api/v1/repos/{owner}/{repo}/collaborators/{username}
+{
+  "permission": "admin"
+}
+```
+
+## 分支操作
+
+### 获取分支列表
+```bash
+GET /api/v1/repos/{owner}/{repo}/branches
+```
+
+### 创建分支
+```bash
+POST /api/v1/repos/{owner}/{repo}/branches
+{
+  "new_branch_name": "feature-branch",
+  "old_branch_name": "main"
+}
+```
+
+## 文件操作
+
+### 获取文件内容
+```bash
+GET /api/v1/repos/{owner}/{repo}/contents/{filepath}
+```
+
+### 创建/更新文件
+```bash
+POST /api/v1/repos/{owner}/{repo}/contents/{filepath}
+{
+  "message": "commit message",
+  "content": "base64_encoded_content",
+  "branch": "main"
+}
+```
+
+### 删除文件
+```bash
+DELETE /api/v1/repos/{owner}/{repo}/contents/{filepath}
+{
+  "message": "delete message",
+  "sha": "file_sha"
+}
+```
+
+## Release 操作
+
+### 获取 Release 列表
+```bash
+GET /api/v1/repos/{owner}/{repo}/releases
+```
+
+### 创建 Release
+```bash
+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 对象或数组。错误响应：
+```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