32d674a4c0
- 修复 delete-runner.md 中的 API 端点从 /api/v1/admin/runners 改为 /api/v1/admin/actions/runners - 更新 SKILL.md 和 repository-operations.md 文档 - 更新 opencode.json 配置
444 lines
13 KiB
Markdown
444 lines
13 KiB
Markdown
---
|
||
name: gitea
|
||
description: Comprehensive Gitea management tool for creating runners, workflows, and repositories with interactive setup
|
||
---
|
||
|
||
# Gitea Management Skill
|
||
|
||
完整的 Gitea 管理工具，提供 Runner、Workflow、仓库的创建和管理功能。
|
||
|
||
## 最新改进 (2026-01-23)
|
||
|
||
### 仓库创建功能增强（简洁高效版）
|
||
1. **智能解析**：自动识别 `组织/仓库` 格式，优先使用指定组织而非默认组织
|
||
2. **简化验证**：默认假设组织存在，API创建失败时清晰提示如何创建组织
|
||
3. **默认私有**：除非明确指定，所有仓库默认创建为私有
|
||
4. **Git集成**：自动检查当前目录是否为Git仓库，提供一键初始化、提交、推送
|
||
5. **错误处理**：详细的Token验证、权限检查，API错误时给出具体解决方案
|
||
6. **工作目录澄清**：仓库操作可在任何目录执行，配置操作在 `~/.config/gitea/`
|
||
7. **流程优化**：减少不必要的预先验证，API失败时再提示，更简洁高效
|
||
|
||
### 使用示例
|
||
```bash
|
||
# 智能解析组织/仓库格式
|
||
/gitea-create-repo shigongcao/shigongcao
|
||
|
||
# 创建公开仓库
|
||
/gitea-create-repo org/project public
|
||
|
||
# 自动初始化并推送
|
||
/gitea-create-repo org/project --init
|
||
```
|
||
|
||
## 工作目录
|
||
|
||
**重要：Gitea 配置和 Runner 相关操作的工作目录为 `~/.config/gitea/`，但仓库操作可以在任何目录执行。**
|
||
|
||
### 配置和 Runner 目录
|
||
```bash
|
||
~/.config/gitea/
|
||
```
|
||
|
||
### 仓库操作目录
|
||
可以在任何项目目录执行，技能会自动：
|
||
1. 从 `~/.config/gitea/config.env` 读取配置
|
||
2. 在当前目录创建仓库、初始化 Git 等
|
||
|
||
### Windows
|
||
```powershell
|
||
# PowerShell
|
||
$env:USERPROFILE\.config\gitea\
|
||
|
||
# CMD
|
||
%USERPROFILE%\.config\gitea\
|
||
|
||
# 完整路径示例
|
||
C:\Users\YourUsername\.config\gitea\
|
||
```
|
||
|
||
**重要区分**：
|
||
- **配置/Runner 操作**：在 `~/.config/gitea/` 目录执行
|
||
- **仓库操作**：可在任何项目目录执行（自动加载配置）
|
||
|
||
**目录结构（所有平台通用）：**
|
||
```
|
||
.config/gitea/
|
||
├── config.env # 主配置文件（Gitea URL、Token、默认组织等）
|
||
├── runners/ # Runner 配置目录
|
||
│ └── runner-*/ # 各个 runner 的独立目录
|
||
└── .gitignore # Git 忽略文件（保护敏感信息）
|
||
```
|
||
|
||
**平台兼容性：**
|
||
- **macOS**: `~/.config/gitea/`（配置目录），任意目录（仓库操作）
|
||
- **Linux**: `~/.config/gitea/`（配置目录），任意目录（仓库操作）
|
||
- **Windows**: `%USERPROFILE%\.config\gitea\`（配置目录），任意目录（仓库操作）
|
||
|
||
**Windows 用户注意事项：**
|
||
- Gitea Act Runner 官方支持 Windows 平台（包括 Host 模式）
|
||
- 该技能文档中的命令和脚本主要基于 Bash，Windows 用户需要：
|
||
- 使用 PowerShell 或 Git Bash 执行命令
|
||
- 调整路径格式（如将 `~/.config/gitea` 改为 `%USERPROFILE%\.config\gitea`）
|
||
- 在 workflow 中指定 `shell: powershell`
|
||
- Windows 安装 act_runner：从 [官方 Releases](https://gitea.com/gitea/act_runner/releases) 下载 Windows 二进制文件
|
||
|
||
## 功能概览
|
||
|
||
| 功能模块 | 文档 | 说明 |
|
||
|---------|------|------|
|
||
| 环境配置 | [setup-guide.md](./setup-guide.md) | 首次使用引导，配置 Gitea URL 和 Token |
|
||
| Runner 管理 | [runner-management.md](./runner-management.md) | 创建、注册、管理 Gitea Act Runner |
|
||
| 自动创建脚本 | [create-runner.md](./create-runner.md) | 包含完整的 Runner 创建 Bash 脚本 |
|
||
| Workflow 生成 | [workflow-generator.md](./workflow-generator.md) | 根据项目类型生成 CI/CD workflow |
|
||
| 仓库操作 | [repository-operations.md](./repository-operations.md) | 创建和配置 Gitea 仓库 |
|
||
| API 参考 | [api-reference.md](./api-reference.md) | Gitea API 常用接口 |
|
||
| 故障排查 | [troubleshooting.md](./troubleshooting.md) | 常见问题解决方案 |
|
||
|
||
## 触发条件
|
||
|
||
当用户提到以下关键词时自动加载此 skill：
|
||
- "gitea"、"runner"、"workflow"
|
||
- "创建 runner"、"配置 runner"、"注册 runner"
|
||
- "生成 workflow"、"CI/CD"
|
||
- "创建仓库"、"gitea 仓库"
|
||
- "gitea 配置"、"gitea token"
|
||
|
||
## 首次使用
|
||
|
||
**重要：** 首次使用前需要配置 Gitea 连接信息。
|
||
|
||
- 配置文件：`~/.config/gitea/config.env`
|
||
- 如果文件不存在，自动启动交互式配置向导
|
||
- 使用 `/gitea-config` 命令查看当前配置
|
||
- 使用 `/gitea-reset` 命令重置配置
|
||
|
||
**新增：Actions Variables 自动注册**
|
||
- 初始化时会自动将配置注册为用户级 variables
|
||
- `GITEA_USERNAME` → `USERNAME` variable
|
||
- `GITEA_WEBHOOK_URL` → `WEBHOOK_URL` variable
|
||
- 可在所有个人仓库的 Actions workflow 中使用
|
||
- 使用方式：`${{ vars.USERNAME }}`、`${{ vars.WEBHOOK_URL }}`
|
||
|
||
**重要**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头
|
||
|
||
详见：[环境配置指南](./setup-guide.md)
|
||
|
||
## 快速命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/gitea-config` | 查看当前 Gitea 配置和 Runner 状态 |
|
||
| `/gitea-reset` | 重置 Gitea 配置（交互式向导） |
|
||
| `/gitea-switch-org` | 切换默认组织 |
|
||
| `/gitea-create-runner` | 创建并启动新 Runner（默认 host 模式） |
|
||
| `/gitea-list-runners` | 列出所有 Runner 及其状态 |
|
||
| `/gitea-delete-runner` | 删除指定 Runner |
|
||
| `/gitea-list-variables` | 列出用户级 Variables |
|
||
| `/gitea-sync-variables` | 同步本地配置到 Gitea Variables |
|
||
| `/gitea-create-repo` | 创建新仓库 |
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置 Gitea 连接
|
||
|
||
首次使用时，系统会自动引导你完成配置：
|
||
|
||
```
|
||
请输入 Gitea 实例地址: https://git.digitevents.com
|
||
请输入 Personal Access Token: ****************
|
||
请输入默认组织名称（可选）: ai
|
||
请输入 Gitea 用户名（用于 Actions）: your_username
|
||
请输入 Gitea 密码: ********
|
||
请输入 Actions 通知 Webhook URL（可选）: https://...
|
||
|
||
✓ 配置已保存到: ~/.config/gitea/config.env
|
||
|
||
正在注册用户级 Variables...
|
||
✓ USERNAME 已创建 (来自 GITEA_USERNAME)
|
||
✓ WEBHOOK_URL 已创建
|
||
```
|
||
|
||
或使用命令：
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
### 2. 创建 Runner
|
||
|
||
```bash
|
||
/gitea-create-runner
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
检查 act_runner 安装状态...
|
||
✓ act_runner 已安装: act_runner version 0.2.13
|
||
|
||
✓ 已加载 Gitea 配置
|
||
URL: https://git.digitevents.com
|
||
|
||
生成 Runner 名称: runner-macbook-pro
|
||
|
||
检测系统环境...
|
||
✓ 系统信息
|
||
操作系统: Darwin (macOS)
|
||
架构: arm64 (ARM64)
|
||
|
||
✓ Runner Labels (Host Mode)
|
||
self-hosted:host,macOS:host,ARM64:host,darwin-arm64:host
|
||
|
||
[自动创建目录、生成配置、注册并启动]
|
||
|
||
✅ Runner 创建完成！
|
||
名称: runner-macbook-pro
|
||
级别: global
|
||
状态: 🟢 运行中
|
||
PID: 12345
|
||
```
|
||
|
||
**说明**：
|
||
- 默认使用 Host Mode（支持 Android SDK、iOS 构建等）
|
||
- 自动检查并安装 act_runner（如未安装）
|
||
- 自动检测系统环境并生成合适的 labels
|
||
- 优先创建全局 Runner（需要管理员 Token）
|
||
- 权限不足时自动降级到组织 Runner
|
||
- 自动后台启动
|
||
|
||
### 3. 生成 Workflow
|
||
|
||
```
|
||
用户: 为我的 Go 项目生成 workflow
|
||
AI: 检测到 Go 项目，服务目录: ./backend
|
||
是否需要构建 Docker 镜像？[Y/n]
|
||
[自动生成 .gitea/workflows/backend.yml]
|
||
```
|
||
|
||
### 4. 创建仓库（智能解析，默认私有）
|
||
|
||
**智能解析特性**：
|
||
- 自动识别 `组织/仓库` 格式，优先使用指定组织
|
||
- 默认创建私有仓库（除非明确指定公开）
|
||
- 支持自动初始化 Git 仓库并推送代码
|
||
|
||
**示例**：
|
||
```
|
||
用户: /gitea-create-repo shigongcao/shigongcao
|
||
AI: [智能解析为 shigongcao 组织下的 shigongcao 仓库]
|
||
✓ 仓库创建成功: shigongcao/shigongcao (私有)
|
||
✓ 组织验证通过
|
||
✓ 可选的 Git 初始化流程...
|
||
|
||
用户: /gitea-create-repo my-project public
|
||
AI: [使用默认组织创建公开仓库]
|
||
✓ 仓库创建成功: ai/my-project (公开)
|
||
|
||
用户: /gitea-create-repo org/project --init
|
||
AI: [创建仓库并自动初始化当前目录的 Git 仓库]
|
||
✓ 仓库创建成功: org/project
|
||
✓ Git 初始化完成
|
||
✓ 代码已推送到远程仓库
|
||
```
|
||
|
||
## 配置管理
|
||
|
||
### 查看配置
|
||
|
||
```bash
|
||
/gitea-config
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
当前 Gitea 配置
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
URL: https://git.digitevents.com
|
||
默认组织: ai
|
||
Token 状态: ✓ 有效 (用户: your_username)
|
||
配置文件: ~/.config/gitea/config.env
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
Runner 信息
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
已配置 Runner 数量: 2
|
||
Runner 目录: ~/.config/gitea/runners
|
||
```
|
||
|
||
### 列出 Runners
|
||
|
||
```bash
|
||
/gitea-list-runners
|
||
```
|
||
|
||
### 切换组织
|
||
|
||
```bash
|
||
/gitea-switch-org my-org
|
||
```
|
||
|
||
### 重置配置
|
||
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
## 配置文件结构
|
||
|
||
```
|
||
~/.config/gitea/
|
||
├── config.env # 主配置文件（含认证信息和 Webhook）
|
||
├── runners/ # Runner 配置目录
|
||
│ ├── runner-macbook-pro/
|
||
│ │ ├── .runner # Runner 注册信息
|
||
│ │ ├── config.yaml # Runner 配置
|
||
│ │ ├── cache/ # Cache 目录
|
||
│ │ └── workspace/ # 工作目录
|
||
│ └── runner-mac-mini/
|
||
│ └── ...
|
||
└── .gitignore # 忽略敏感文件
|
||
```
|
||
|
||
**config.env 包含的配置项**：
|
||
- `GITEA_URL`: Gitea 实例地址
|
||
- `GITEA_TOKEN`: Personal Access Token
|
||
- `GITEA_DEFAULT_ORG`: 默认组织
|
||
- `GITEA_USERNAME`: Gitea 用户名（自动注册为 `USERNAME` variable）
|
||
- `GITEA_PASSWORD`: Gitea 密码（仅本地使用）
|
||
- `GITEA_WEBHOOK_URL`: Actions 通知 Webhook（自动注册为 `WEBHOOK_URL` variable）
|
||
|
||
## 使用流程
|
||
|
||
### 典型的 Gitea 项目设置流程
|
||
|
||
1. **初始化配置**（仅首次）
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
2. **创建仓库**
|
||
```bash
|
||
/gitea-create-repo myorg/myproject
|
||
```
|
||
|
||
3. **创建 Runner**（如果需要自托管 CI/CD）
|
||
```bash
|
||
/gitea-create-runner
|
||
```
|
||
|
||
4. **生成 Workflow**
|
||
```
|
||
用户: 为这个项目生成 workflow
|
||
```
|
||
|
||
5. **推送代码并触发 CI/CD**
|
||
```bash
|
||
git push origin main
|
||
```
|
||
|
||
## Runner 管理
|
||
|
||
### 创建 Runner
|
||
|
||
使用命令快速创建：
|
||
```bash
|
||
/gitea-create-runner
|
||
```
|
||
|
||
特性：
|
||
- 自动检查并安装 act_runner
|
||
- 自动检测系统环境（OS、架构）
|
||
- 默认使用 Host Mode（支持原生工具）
|
||
- 自动生成配置并启动
|
||
- 优先创建全局 Runner
|
||
|
||
详见：[Runner 管理](./runner-management.md)
|
||
|
||
### 查看 Runner 状态
|
||
|
||
```bash
|
||
/gitea-list-runners
|
||
```
|
||
|
||
显示：
|
||
- 运行状态（运行中/已停止）
|
||
- PID
|
||
- 配置信息（容量、超时、labels）
|
||
- 启动命令
|
||
|
||
### 删除 Runner
|
||
|
||
```bash
|
||
/gitea-delete-runner runner-macbook-pro
|
||
```
|
||
|
||
会自动：
|
||
- 停止运行中的进程
|
||
- 可选从 Gitea 服务器注销
|
||
- 删除所有相关文件（配置、cache、workspace）
|
||
|
||
## Workflow 模板
|
||
|
||
支持以下项目类型的 workflow 模板：
|
||
|
||
| 类型 | 模板文档 | 适用场景 |
|
||
|------|---------|---------|
|
||
| Go 后端 | [go-backend.md](./workflow-templates/go-backend.md) | API 服务、微服务、CLI 工具 |
|
||
| Node.js 前端 | [nodejs-frontend.md](./workflow-templates/nodejs-frontend.md) | React/Vue/Vite/Next.js |
|
||
| Android 应用 | [android-app.md](./workflow-templates/android-app.md) | Kotlin/Java/Jetpack Compose |
|
||
| 微信小程序 | [wechat-miniprogram.md](./workflow-templates/wechat-miniprogram.md) | 微信小程序 CI/CD |
|
||
|
||
AI 会自动：
|
||
- 检测项目类型
|
||
- 选择合适的模板
|
||
- 填充项目特定的变量（路径、服务名等）
|
||
- 生成完整的 workflow 文件
|
||
|
||
详见：[Workflow 生成器](./workflow-generator.md)
|
||
|
||
## API 调用
|
||
|
||
所有与 Gitea 服务器的交互都通过 API 完成，使用配置文件中的：
|
||
- `GITEA_URL`: Gitea 实例地址
|
||
- `GITEA_TOKEN`: Personal Access Token
|
||
|
||
详见：[API 参考](./api-reference.md)
|
||
|
||
## 安全性
|
||
|
||
- 配置文件权限：`600`（仅所有者可读写）
|
||
- Token 不会在日志中显示
|
||
- `.gitignore` 自动排除敏感文件
|
||
- 删除 runner 时可选择从服务器注销
|
||
|
||
## 故障排查
|
||
|
||
常见问题：
|
||
- 连接失败：检查 URL 和网络
|
||
- Token 无效：检查 Token 权限和有效期
|
||
- Runner 无法启动：检查端口占用和权限
|
||
- Workflow 无法触发：检查 labels 匹配
|
||
|
||
详见：[故障排查](./troubleshooting.md)
|
||
|
||
## 版本
|
||
|
||
- **Skill Version**: 1.1
|
||
- **Last Updated**: 2026-01-23
|
||
- **整合内容**: gitea-runner + gitea-workflow + 增强仓库管理
|
||
- **主要改进**:
|
||
- 仓库创建智能解析（优先使用指定组织）
|
||
- **简化验证**：默认假设组织存在，API失败时提示创建组织
|
||
- 默认私有仓库策略（除非明确指定公开）
|
||
- **完整 Git 集成**：自动检查Git状态，提供一键初始化、提交、推送
|
||
- **简洁高效**：减少预先验证，API失败时给出具体解决方案
|
||
- 工作目录概念澄清（配置 vs 仓库操作）
|
||
|
||
## 相关资源
|
||
|
||
- [Gitea 官方文档](https://docs.gitea.com/)
|
||
- [Gitea Actions 文档](https://docs.gitea.com/usage/actions/overview)
|
||
- [Gitea API 文档](https://docs.gitea.com/api/1.20/)
|
||
- [Act Runner 文档](https://docs.gitea.com/usage/actions/act-runner)
|