Files

voson dffa3fae12 feat: 重构工作流体系，将命令模式迁移为技能文档

2026-01-21 15:55:57 +08:00

11 KiB

Raw Blame History

name, description

name	description
gitea	Comprehensive Gitea management tool for creating runners, workflows, and repositories with interactive setup

Gitea Management Skill

完整的 Gitea 管理工具，提供 Runner、Workflow、仓库的创建和管理功能。

工作目录

重要：该技能和所有相关命令的工作目录统一为：

macOS / Linux

~/.config/gitea/

Windows

# 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 下载 Windows 二进制文件

功能概览

功能模块	文档	说明
环境配置	setup-guide.md	首次使用引导，配置 Gitea URL 和 Token
Runner 管理	runner-management.md	创建、注册、管理 Gitea Act Runner
自动创建脚本	create-runner.md	包含完整的 Runner 创建 Bash 脚本
Workflow 生成	workflow-generator.md	根据项目类型生成 CI/CD workflow
仓库操作	repository-operations.md	创建和配置 Gitea 仓库
API 参考	api-reference.md	Gitea API 常用接口
故障排查	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_ 开头

详见：环境配置指南

快速命令

命令	说明
`/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 已创建

或使用命令：

/gitea-reset

2. 创建 Runner

/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

配置管理

查看配置

/gitea-config

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
当前 Gitea 配置
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  URL:        https://git.digitevents.com
  默认组织:    ai
  Token 状态:  ✓ 有效 (用户: your_username)
  配置文件:    ~/.config/gitea/config.env

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Runner 信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  已配置 Runner 数量: 2
  Runner 目录: ~/.config/gitea/runners

列出 Runners

/gitea-list-runners

切换组织

/gitea-switch-org my-org

重置配置

/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 项目设置流程

初始化配置（仅首次）
```
/gitea-reset
```
创建仓库
```
/gitea-create-repo myorg/myproject
```
创建 Runner（如果需要自托管 CI/CD）
```
/gitea-create-runner
```
生成 Workflow
```
用户: 为这个项目生成 workflow
```
推送代码并触发 CI/CD
```
git push origin main
```

Runner 管理

创建 Runner

使用命令快速创建：

/gitea-create-runner

特性：

自动检查并安装 act_runner
自动检测系统环境（OS、架构）
默认使用 Host Mode（支持原生工具）
自动生成配置并启动
优先创建全局 Runner

详见：Runner 管理

查看 Runner 状态

/gitea-list-runners

显示：

运行状态（运行中/已停止）
PID
配置信息（容量、超时、labels）
启动命令

删除 Runner

/gitea-delete-runner runner-macbook-pro

会自动：

停止运行中的进程
可选从 Gitea 服务器注销
删除所有相关文件（配置、cache、workspace）

Workflow 模板

支持以下项目类型的 workflow 模板：

类型	模板文档	适用场景
Go 后端	go-backend.md	API 服务、微服务、CLI 工具
Node.js 前端	nodejs-frontend.md	React/Vue/Vite/Next.js
Android 应用	android-app.md	Kotlin/Java/Jetpack Compose
微信小程序	wechat-miniprogram.md	微信小程序 CI/CD

AI 会自动：

检测项目类型
选择合适的模板
填充项目特定的变量（路径、服务名等）
生成完整的 workflow 文件

详见：Workflow 生成器

API 调用

所有与 Gitea 服务器的交互都通过 API 完成，使用配置文件中的：

GITEA_URL: Gitea 实例地址
GITEA_TOKEN: Personal Access Token

详见：API 参考

安全性

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

故障排查

常见问题：

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

详见：故障排查

版本

Skill Version: 1.0
Last Updated: 2026-01-12
整合内容: gitea-runner + gitea-workflow
新增功能: 统一配置管理、Runner CRUD、智能 labels 检测

11 KiB Raw Blame History Unescape Escape