---
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)