389 lines
11 KiB
Markdown
389 lines
11 KiB
Markdown
---
|
||
name: gitea
|
||
description: Comprehensive Gitea management tool for creating runners, workflows, and repositories with interactive setup
|
||
---
|
||
|
||
# Gitea Management Skill
|
||
|
||
完整的 Gitea 管理工具，提供 Runner、Workflow、仓库的创建和管理功能。
|
||
|
||
## 工作目录
|
||
|
||
**重要：该技能和所有相关命令的工作目录统一为：**
|
||
|
||
### macOS / Linux
|
||
```bash
|
||
~/.config/gitea/
|
||
```
|
||
|
||
### Windows
|
||
```powershell
|
||
# PowerShell
|
||
$env:USERPROFILE\.config\gitea\
|
||
|
||
# CMD
|
||
%USERPROFILE%\.config\gitea\
|
||
|
||
# 完整路径示例
|
||
C:\Users\YourUsername\.config\gitea\
|
||
```
|
||
|
||
所有配置文件、Runner 目录、日志文件都存储在此目录下。请确保该目录具有适当的读写权限。
|
||
|
||
**目录结构（所有平台通用）：**
|
||
```
|
||
.config/gitea/
|
||
├── config.env # 主配置文件（Gitea URL、Token、默认组织等）
|
||
├── runners/ # Runner 配置目录
|
||
│ └── runner-*/ # 各个 runner 的独立目录
|
||
└── .gitignore # Git 忽略文件（保护敏感信息）
|
||
```
|
||
|
||
**平台兼容性：**
|
||
- **macOS**: `~/.config/gitea/`（完全支持）
|
||
- **Linux**: `~/.config/gitea/`（完全支持）
|
||
- **Windows**: `%USERPROFILE%\.config\gitea\`（Act Runner 支持，但该技能的命令和脚本需要适配）
|
||
|
||
**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 |
|
||
| 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. 创建仓库
|
||
|
||
```
|
||
用户: /gitea-create-repo my-project
|
||
AI: [使用配置的 Gitea URL 和默认组织创建仓库]
|
||
✓ 仓库创建成功: ai/my-project
|
||
```
|
||
|
||
## 配置管理
|
||
|
||
### 查看配置
|
||
|
||
```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.0
|
||
- **Last Updated**: 2026-01-12
|
||
- **整合内容**: gitea-runner + gitea-workflow
|
||
- **新增功能**: 统一配置管理、Runner CRUD、智能 labels 检测
|
||
|
||
## 相关资源
|
||
|
||
- [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)
|