opencode/skill/gitea/setup-guide.md

Gitea 环境配置指南

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

概述

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

~/.config/gitea/config.env

配置目录结构

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

快速配置

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

运行配置命令：

/gitea-reset

按照提示输入信息即可。

方法 2: 自然语言请求

直接告诉 AI：

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

AI 会自动启动配置向导。

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

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

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     (企业微信)

使用方式：

- 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 中使用：

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

配置文件内容：

# 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

配置验证

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

/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 不符合需求，可以手动覆盖：

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

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

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

配置管理

查看当前配置

/gitea-config

显示：

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

切换默认组织

/gitea-switch-org new-org-name

重置配置

/gitea-reset

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

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

更新配置

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

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

方法 2: 手动编辑

vim ~/.config/gitea/config.env

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

多环境配置

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

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

# 开发环境
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: 创建切换脚本

# ~/.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 ~/.config/gitea/switch-env.sh dev

安全最佳实践

1. 文件权限

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

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

2. Token 安全

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

3. 配置备份

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

# 创建备份（移除敏感信息）
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 重新配置

解决方案：

/gitea-reset

下一步

配置完成后，你可以：

1. 创建第一个 Runner（自动后台启动）：

   用户: 创建一个 runner
   

   • 默认创建全局 Runner（可用于所有组织和仓库）
   • 如果 Token 没有管理员权限，自动降级到组织 Runner
   • 创建后 Runner 会自动在后台运行

2. 创建仓库：

   /gitea-create-repo my-project
   

3. 生成 Workflow：

   用户: 为我的项目生成 workflow
   

4. 查看配置：

   /gitea-config
   

---

相关文档：

• Runner 管理
• Workflow 生成器
• 仓库操作
• API 参考