# Gitea 环境配置指南

首次使用 Gitea skill 前的完整配置指南。

## 概述

Gitea skill 需要配置连接信息才能与你的 Gitea 实例交互。配置信息存储在：

```
~/.config/gitea/config.env
```

## 配置目录结构

```
~/.config/gitea/
├── config.env          # 主配置文件（包含 URL、Token、默认组织等）
├── runners/            # Runner 配置目录
│   └── runner-*/       # 各个 runner 的独立目录
└── .gitignore          # Git 忽略文件（保护敏感信息）
```

## 快速配置

### 方法 1: 使用交互式向导（推荐）

运行配置命令：

```bash
/gitea-reset
```

按照提示输入信息即可。

### 方法 2: 自然语言请求

直接告诉 AI：

```
用户: 配置 gitea
用户: 初始化 gitea 连接
用户: 设置 gitea 环境
```

AI 会自动启动配置向导。

### 方法 3: 手动创建配置文件

如果你熟悉配置格式，可以手动创建：

```bash
mkdir -p ~/.config/gitea/runners
cat > ~/.config/gitea/config.env << 'EOF'
GITEA_URL=https://git.digitevents.com
GITEA_TOKEN=your_personal_access_token
GITEA_DEFAULT_ORG=your_org_name

GITEA_RUNNER_CAPACITY=2
GITEA_RUNNER_TIMEOUT=3h
EOF

chmod 600 ~/.config/gitea/config.env
```

## 交互式配置流程

### 步骤 1: 输入 Gitea 实例地址

```
请输入 Gitea 实例地址 (例如: https://git.digitevents.com): 
```

**要求**：
- 必须以 `http://` 或 `https://` 开头
- 不要包含尾随斜杠
- 确保可以从当前网络访问

**示例**：
```
✓ https://git.digitevents.com
✓ https://gitea.example.com
✗ git.digitevents.com          (缺少协议)
✗ https://gitea.com/           (包含尾随斜杠)
```

### 步骤 2: 输入 Personal Access Token

```
请输入 Personal Access Token: 
```

**获取 Token 的步骤**：

1. 登录 Gitea
2. 点击右上角头像 → **设置**
3. 左侧菜单选择 **应用** → **访问令牌**
4. 点击 **生成新令牌**
5. 设置令牌名称（如 `opencode-cli`）
6. 选择权限（见下方推荐权限）
7. 点击 **生成令牌**
8. 复制生成的 Token（只显示一次！）

**推荐权限**：

| 权限 | 用途 | 是否必需 |
|------|------|---------|
| `repo` | 创建和管理仓库 | ✅ 必需 |
| `admin:org` | 创建组织级 Runner | ✅ 推荐 |
| `write:runner` | 管理 Runner | ✅ 推荐 |
| `write:user` | 创建用户级 Variables | ✅ 推荐 |
| `admin:repo_hook` | 配置 Webhooks | ⚠️ 可选 |
| `write:issue` | 创建 Release | ⚠️ 可选 |

**安全提示**：
- Token 等同于密码，请妥善保管
- 不要在公开场合分享 Token
- 定期轮换 Token（建议每 3-6 个月）
- 使用最小权限原则

### 步骤 3: 测试连接

```
正在测试连接...
✓ 连接成功！
```

系统会调用 Gitea API 验证：
- URL 是否可访问
- Token 是否有效
- 网络是否正常

**如果失败**：
- 检查 URL 是否正确
- 检查 Token 是否复制完整
- 检查网络连接
- 检查防火墙设置

### 步骤 4: 验证 Token 权限

```
正在检查 Token 权限...
  ✓ repo (仓库管理)
  ✓ admin:org (组织管理)
  ✓ write:runner (Runner 管理)
  ⚠ 缺少 admin:repo_hook 权限（可能影响 Webhook 配置）
```

系统会测试 Token 的实际权限，并给出建议。

**权限不足时**：
- 如果缺少必需权限，建议重新创建 Token
- 如果只缺少可选权限，可以继续使用
- 后续需要时可以更新 Token

### 步骤 5: 输入默认组织（可选）

```
请输入默认组织名称 (可选，回车跳过): 
```

**作用**：
- 创建仓库时，如果不指定 owner，使用此默认组织
- 创建组织级 Runner 时使用
- 可以随时使用 `/gitea-switch-org` 切换

**示例**：
```
ai          → 创建仓库时使用 ai/repo-name
my-team     → 创建仓库时使用 my-team/repo-name
(留空)      → 创建仓库时使用当前登录用户
```

**注意**：留空是完全可以的，系统会自动使用当前登录用户创建个人仓库。

### 步骤 6: 输入 Gitea 用户名（用于 Actions Variables）

```
请输入 Gitea 用户名 (将创建为用户级 variable): 
```

**作用**：
- 此用户名将自动注册到 Gitea 用户级 variables（变量名：`USERNAME`）
- 可在所有个人仓库的 Actions workflow 中通过 `${{ vars.USERNAME }}` 使用
- 用于需要 Git 操作的 workflow（如推送代码、创建 tag 等）

**示例**：
```
your_username → 在 workflow 中可使用 ${{ vars.USERNAME }}
john        → 你的 Gitea 登录用户名
```

**重要说明**：
- Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头
- 因此配置项 `GITEA_USERNAME` 会被注册为 `USERNAME` variable
- 如果此 variable 已存在于 Gitea 服务器，系统会自动更新为新值

### 步骤 7: 输入 Gitea 密码（用于 Actions）

```
请输入 Gitea 密码: 
```

**作用**：
- 密码将存储在本地配置文件 `config.env` 中（权限 600）
- 用于需要认证的 Git 操作
- 也可以选择在 workflow 中使用 Secret 方式（需要手动创建）

**安全说明**：
- ✅ 配置文件权限为 600（仅所有者可读写）
- ✅ `.gitignore` 自动排除配置文件
- ⚠️ 不建议在公共环境使用明文密码
- 💡 建议使用 Personal Access Token 替代密码

**留空说明**：如果不需要在 workflow 中进行 Git 推送操作，可以留空。

### 步骤 8: 输入 Actions 通知 Webhook URL（可选）

```
请输入 Actions 通知 Webhook URL (可选，回车跳过): 
```

**作用**：
- 用于 workflow 完成后发送通知到第三方平台（如飞书、钉钉、企业微信等）
- 此 URL 将自动注册到 Gitea 用户级 variables（变量名：`WEBHOOK_URL`）
- 可在 workflow 中通过 `${{ vars.WEBHOOK_URL }}` 使用

**示例**：
```
https://www.feishu.cn/flow/api/trigger-webhook/xxx           (飞书)
https://oapi.dingtalk.com/robot/send?access_token=xxx        (钉钉)
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx     (企业微信)
```

**使用方式**：
```yaml
- name: 发送通知
  run: |
    curl -X POST "${{ vars.WEBHOOK_URL }}" \
      -H "Content-Type: application/json" \
      -d '{"msg_type":"text","content":{"text":"构建完成"}}'
```

**说明**：
- 留空则不创建 `WEBHOOK_URL` variable
- 如果此 variable 已存在于 Gitea 服务器，系统会更新为新值

### 步骤 9: 注册用户级 Variables

```
正在检查并注册用户级 Variables...
  检查 USERNAME...
  ✓ USERNAME 已创建
  检查 WEBHOOK_URL...
  ✓ WEBHOOK_URL 已创建
```

系统会自动调用 Gitea API 创建以下用户级 variables：

| Variable 名称 | 来源配置 | 说明 |
|--------------|---------|------|
| `USERNAME` | `GITEA_USERNAME` | Gitea 用户名 |
| `WEBHOOK_URL` | `GITEA_WEBHOOK_URL` | Actions 通知 Webhook |

**重要**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以 `GITEA_USERNAME` 配置项会被注册为 `USERNAME` variable。

**API 端点**：
```
POST /api/v1/user/actions/variables/{variable_name}
```

**在 Workflow 中使用**：
```yaml
steps:
  - name: 使用 Variables
    run: |
      echo "用户名: ${{ vars.USERNAME }}"
      echo "Webhook: ${{ vars.WEBHOOK_URL }}"
```

**查看已创建的 Variables**：
- 访问：`https://git.digitevents.com/user/settings/actions/variables`
- 或使用命令：`/gitea-list-variables`

### 步骤 10: 保存配置

```
✓ 配置已保存
  配置文件: ~/.config/gitea/config.env
  Runner 目录: ~/.config/gitea/runners
```

配置文件内容：

```bash
# Gitea Configuration
# Generated at 2026-01-12 22:30:00

GITEA_URL=https://git.digitevents.com
GITEA_TOKEN=git_xxxxxxxxxxxxxxxxxxxx
GITEA_DEFAULT_ORG=ai

# Gitea 仓库认证信息（用于 Actions）
GITEA_USERNAME=your_username
GITEA_PASSWORD=your_password_here

# Actions 通知 Webhook（可选）
GITEA_WEBHOOK_URL=https://www.feishu.cn/flow/api/trigger-webhook/xxx

# Runner Default Settings
GITEA_RUNNER_CAPACITY=2
GITEA_RUNNER_TIMEOUT=3h

# Optional: Override auto-detected labels
# GITEA_RUNNER_LABELS=custom-label-1:host,custom-label-2:host
```

## 配置验证

配置完成后，验证配置是否正确：

```bash
/gitea-config
```

应该看到：

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

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

## 配置文件说明

### 必需配置项

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `GITEA_URL` | Gitea 实例地址 | `https://git.digitevents.com` |
| `GITEA_TOKEN` | Personal Access Token | `git_xxxxxxxxxx` |

### 推荐配置项（用于 Actions）

| 配置项 | 说明 | 示例 | 自动创建为 Variable |
|--------|------|------|-------------------|
| `GITEA_USERNAME` | Gitea 用户名 | `your_username` | ✅ 是 → `USERNAME` |
| `GITEA_PASSWORD` | Gitea 密码 | `your_password` | ❌ 否（仅本地使用） |
| `GITEA_WEBHOOK_URL` | Actions 通知 Webhook | `https://...` | ✅ 是 → `WEBHOOK_URL` |

**说明**：
- 标记为 ✅ 的配置项会在初始化时自动创建为 Gitea 用户级 variables
- 这些 variables 可在所有个人仓库的 Actions workflow 中使用
- 使用方式：`${{ vars.USERNAME }}`、`${{ vars.WEBHOOK_URL }}`
- **注意**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以会自动转换名称

### 可选配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `GITEA_DEFAULT_ORG` | 默认组织名称 | 无 |
| `GITEA_RUNNER_CAPACITY` | Runner 并发任务数 | `2` |
| `GITEA_RUNNER_TIMEOUT` | Runner 任务超时时间 | `3h` |
| `GITEA_RUNNER_LABELS` | 覆盖自动检测的 labels | 自动检测 |

### 自定义 Runner Labels

如果自动检测的 labels 不符合需求，可以手动覆盖：

```bash
# 编辑配置文件
vim ~/.config/gitea/config.env

# 取消注释并修改
GITEA_RUNNER_LABELS=self-hosted:host,linux:host,x64:host,custom:host
```

创建新 Runner 时会优先使用此配置。

## 配置管理

### 查看当前配置

```bash
/gitea-config
```

显示：
- Gitea URL
- 默认组织
- Token 状态和关联用户
- 已配置的 Runner 数量
- 配置文件路径

### 切换默认组织

```bash
/gitea-switch-org new-org-name
```

### 重置配置

```bash
/gitea-reset
```

会重新启动配置向导，覆盖现有配置。

**警告**：重置配置不会影响已创建的 Runner，但 Runner 会继续使用旧的注册信息。

### 更新配置

#### 方法 1: 使用命令（推荐）

```bash
/gitea-reset                    # 完整重置
/gitea-switch-org my-org        # 只切换组织
```

#### 方法 2: 手动编辑

```bash
vim ~/.config/gitea/config.env
```

修改后无需重启，下次使用时自动生效。

## 多环境配置

如果需要管理多个 Gitea 实例，推荐做法：

### 方法 1: 使用不同的配置文件

```bash
# 开发环境
cp ~/.config/gitea/config.env ~/.config/gitea/config.dev.env

# 生产环境
cp ~/.config/gitea/config.env ~/.config/gitea/config.prod.env

# 使用时手动切换
cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
```

### 方法 2: 创建切换脚本

```bash
# ~/.config/gitea/switch-env.sh
#!/bin/bash

case "$1" in
  dev)
    cp ~/.config/gitea/config.dev.env ~/.config/gitea/config.env
    echo "✓ 切换到开发环境"
    ;;
  prod)
    cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
    echo "✓ 切换到生产环境"
    ;;
  *)
    echo "用法: $0 {dev|prod}"
    exit 1
    ;;
esac
```

使用：
```bash
bash ~/.config/gitea/switch-env.sh dev
```

## 安全最佳实践

### 1. 文件权限

确保配置文件只有所有者可读写：

```bash
chmod 600 ~/.config/gitea/config.env
```

### 2. Token 安全

- ✅ 使用最小权限原则
- ✅ 定期轮换 Token
- ✅ 不要将 Token 提交到 Git
- ✅ 使用 `.gitignore` 排除配置文件
- ❌ 不要在公开场合分享 Token
- ❌ 不要使用永不过期的 Token

### 3. 配置备份

定期备份配置（移除 Token 后）：

```bash
# 创建备份（移除敏感信息）
grep -v "GITEA_TOKEN" ~/.config/gitea/config.env > ~/gitea-config-backup.env
```

### 4. .gitignore 配置

自动生成的 `.gitignore` 文件：

```
# ~/.config/gitea/.gitignore
config.env
runners/*/.runner
runners/*/.env
```

确保敏感文件不会被意外提交。

## 故障排查

### 连接失败

**症状**：
```
❌ 连接失败 (HTTP 404)
请检查 URL 和 Token 是否正确
```

**解决方案**：
1. 检查 URL 是否正确（不要包含 `/api/v1`）
2. 检查网络连接
3. 尝试在浏览器中访问 URL
4. 检查防火墙设置

### Token 无效

**症状**：
```
❌ 连接失败 (HTTP 401)
```

**解决方案**：
1. Token 可能已过期，重新生成
2. Token 可能被撤销，检查 Gitea 设置
3. Token 复制不完整，重新复制
4. 确认 Token 有足够的权限

### 权限不足

**症状**：
```
⚠ 缺少 admin:org 权限（可能影响组织 Runner 创建）
```

**解决方案**：
1. 重新创建 Token，选择更多权限
2. 联系 Gitea 管理员提升权限
3. 使用个人 Runner 而非组织 Runner

### 配置文件损坏

**症状**：
```
❌ 配置文件不完整，请运行 /gitea-reset 重新配置
```

**解决方案**：
```bash
/gitea-reset
```

## 下一步

配置完成后，你可以：

1. **创建第一个 Runner**（自动后台启动）：
   ```
   用户: 创建一个 runner
   ```
   - 默认创建全局 Runner（可用于所有组织和仓库）
   - 如果 Token 没有管理员权限，自动降级到组织 Runner
   - 创建后 Runner 会自动在后台运行

2. **创建仓库**：
   ```bash
   /gitea-create-repo my-project
   ```

3. **生成 Workflow**：
   ```
   用户: 为我的项目生成 workflow
   ```

4. **查看配置**：
   ```bash
   /gitea-config
   ```

---

**相关文档**：
- [Runner 管理](./runner-management.md)
- [Workflow 生成器](./workflow-generator.md)
- [仓库操作](./repository-operations.md)
- [API 参考](./api-reference.md)