# 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