---
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 |
| SSH 密钥管理 | [ssh-key-management.md](./ssh-key-management.md) | 创建、部署 SSH 密钥，配置本地客户端 |
| 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"
- "ssh key"、"ssh密钥"、"gitea ssh"、"部署密钥"

## 首次使用

**重要：** 首次使用前需要配置 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 Actions 不允许变量和密钥名称以 `GITEA_` 或 `GITHUB_` 开头
- 推荐命名：
  - `REGISTRY_TOKEN`（替代 `GITEA_TOKEN`）
  - `REGISTRY_URL` → 使用内置 `${{ env.registry }}`
  - `USERNAME` → 使用内置 `${{ github.actor }}`
  - `WEBHOOK_URL`（已自动注册为 variable）

详见：[环境配置指南](./setup-guide.md)

## 快速命令

| 命令 | 说明 |
|------|------|
| `/gitea-config` | 查看当前 Gitea 配置和 Runner 状态 |
| `/gitea-reset` | 重置 Gitea 配置（交互式向导） |
| `/gitea-switch-org` | 切换默认组织 |
| `/gitea-setup-ssh` | 创建 SSH 密钥并部署到 Gitea 服务器 |
| `/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 模板：

| 类型 | 模板文档 | 适用场景 |
|------|---------|---------|
| **Rust 后端** | [rust-backend.md](./workflow-templates/rust-backend.md) | **Rust API 服务、微服务、CLI 工具** |
| 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)

## 变量命名规范

**⚠️ 重要限制**：Gitea Actions 不允许变量和密钥名称以 `GITEA_` 或 `GITHUB_` 开头

### 推荐命名约定

| 原名称 | 推荐替代 | 说明 |
|--------|----------|------|
| `GITEA_TOKEN` | `REGISTRY_TOKEN` | Container registry 访问令牌 |
| `GITEA_URL` | `${{ env.registry }}` | 使用内置变量自动获取当前实例地址 |
| `GITEA_USERNAME` | `${{ github.actor }}` | 使用内置变量获取当前用户 |
| `GITHUB_TOKEN` | `RELEASE_TOKEN` | 用于创建 Release 的 API 令牌 |

### 内置变量利用

Gitea Actions 提供的内置变量（推荐优先使用）：
- `${{ env.registry }}`: 当前 Gitea 实例的 registry 地址
- `${{ github.actor }}`: 触发 workflow 的用户名
- `${{ github.repository }}`: 当前仓库的 `owner/repo` 格式
- `${{ github.server_url }}`: Gitea 实例的基础 URL

### Variables vs Secrets

**Variables**（明文存储，适用于非敏感配置）：
- `USERNAME`: 用户名（自动从配置同步）
- `WEBHOOK_URL`: 通知 webhook 地址
- `DEFAULT_ORG`: 默认组织名

**Secrets**（加密存储，适用于敏感信息）：
- `REGISTRY_TOKEN`: Container registry 密码
- `RELEASE_TOKEN`: Release 创建 API 令牌

## 安全性

- 配置文件权限：`600`（仅所有者可读写）
- Token 不会在日志中显示
- `.gitignore` 自动排除敏感文件
- 删除 runner 时可选择从服务器注销

## 故障排查

常见问题：
- 连接失败：检查 URL 和网络
- Token 无效：检查 Token 权限和有效期
- Runner 无法启动：检查端口占用和权限
- Workflow 无法触发：检查 labels 匹配

详见：[故障排查](./troubleshooting.md)

## 版本

- **Skill Version**: 1.3
- **Last Updated**: 2026-01-29
- **整合内容**: gitea-runner + gitea-workflow + 增强仓库管理 + SSH 密钥管理 + Rust 模板
- **主要改进**:
  - 仓库创建智能解析（优先使用指定组织）
  - **简化验证**：默认假设组织存在，API失败时提示创建组织
  - 默认私有仓库策略（除非明确指定公开）
  - **完整 Git 集成**：自动检查Git状态，提供一键初始化、提交、推送
  - **简洁高效**：减少预先验证，API失败时给出具体解决方案
  - 工作目录概念澄清（配置 vs 仓库操作）
  - **SSH 密钥管理**：完整的密钥创建、部署和跨设备使用指南

## 相关资源

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