# gitea-skills

**Repository Path**: lu9944_admin/gitea-skills

## Basic Information

- **Project Name**: gitea-skills
- **Description**: 用于 AI 自动管理自部署的 gitea 仓库
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitea-skills — Gitea 网站运维 Skill + CLI

通过 **Gitea 官方 API(`/api/v1`)** 管理 Gitea 站点的 opencode Skill + 命令行工具。
纯 **Python 3.8+ 标准库**实现,零第三方依赖。

- 登录一次,API Token 保存本机(`~/.config/gitea-cli/<profile>.json`,0600),后续免登录;
- `doctor` 六项环境自检,`api list / api describe` 原始 API 发现(549 条源码路由 + Swagger 元数据);
- 覆盖 repo / branch / tag / file / issue / pull / org / user / admin / release / hook 全模块;
- 输出面向 AI 消费:默认人类可读表格,`--json` 输出纯 JSON,错误统一带退出码。

## 目录结构

```
gitea-skills/
├── SKILL.md                      # opencode Skill 主体
├── commands.md                   # 完整命令速查表
├── .env.example                  # 配置模板
├── docs/api-gitea.json           # API 路由目录(生成产物,已提交)
├── references/api-notes.md       # Gitea API 要点与源码对照
├── scripts/generate_api_catalog.py  # 路由目录生成器
└── cli/
    ├── gitea-cli                 # 可执行入口(shebang python3)
    └── gitea_cli/                # Python 包(17 个模块)
```

## 安装

```sh
# 方式一:直接使用
./cli/gitea-cli --help

# 方式二:链接到 PATH
ln -s "$(pwd)/cli/gitea-cli" ~/.local/bin/gitea-cli

# 方式三:作为 opencode skill
cp -r gitea-skills ~/.config/opencode/skills/gitea-cli
```

## 配置

```sh
cp .env.example .env
```

```dotenv
GITEA_URL=http://git.example.com:3000   # 站点地址(子路径部署写完整前缀)
GITEA_USERNAME=your_name
GITEA_PASSWORD=your_password
# GITEA_TOKEN=                          # 已有 Token(设置后跳过登录创建)
# GITEA_OTP=                            # 2FA TOTP 动态码(自动化场景)
# GITEA_INSECURE=false                  # 自签名 HTTPS 设为 true
```

优先级:**命令行参数 > 环境变量 > .env 文件**;会话 Token 优先于用户名+密码。
`.env` 查找顺序:当前目录 → 可执行文件目录 → `--env <PATH>` 显式指定。

## 快速开始

```sh
gitea-cli doctor        # 环境自检(所有操作前必须先通过)
gitea-cli login         # 登录并保存 Token
gitea-cli status        # 查看会话
gitea-cli repo list     # 开始使用
```

## 安全约定

1. `.env` 含密码,已被 `.gitignore` 忽略,**严禁提交仓库**;
2. 会话文件 `~/.config/gitea-cli/<profile>.json` 权限 0600,内含 Token 明文;
3. 密码/OTP/Token 不写入日志与输出;`status` 只显示 Token 前 8 位指纹;
4. 危险操作(`repo delete`、`org delete`、`admin user delete` 等)非 `--force` 时需交互确认;
5. 网络与认证错误给出可操作提示,但不回显凭据。

## 重新生成 API 路由目录

```sh
python3 scripts/generate_api_catalog.py --source /path/to/gitea --output docs/api-gitea.json
```

解析 `routers/api/v1/api.go` 的 go-chi 路由注册(嵌套 Group、Combo 链式、helper 函数),
并与 `templates/swagger/v1-swagger.generated.json` 合并;输出统计(总数 / Swagger 覆盖率 / 无 handler 数)。

## 退出码

| 码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 配置/参数/网络错误 |
| 2 | 服务端 5xx |
| 3 | 认证失败(401) |
| 4 | 无权限(403) |
| 5 | 资源不存在(404) |
| 6 | 校验失败(400/422) |
| 7 | doctor 检查未通过 |

## License

MIT