ai-proj-helper/skills-dev/gitea-plugin/skills/SKILL.md

name, description

name	description
gitea	Gitea 代码托管与 CI/CD 管理。用于 Gitea Actions workflow 管理、Runner 管理、PR 操作、仓库配置。当用户提到 Gitea、Actions、Runner、CI/CD workflow、PR 检查相关任务时自动激活。

Gitea Skill

Gitea 代码托管平台管理，覆盖 Actions CI/CD、Runner、PR、仓库配置。

服务器信息

服务	地址	SSH
Gitea Web	https://gitea.pipexerp.com	—
Gitea SSH	gitea.pipexerp.com:10022	ssh -i ~/.ssh/id_ed25519 git@gitea.pipexerp.com -p 10022
Gitea 服务器	123.56.89.187	ssh -i ~/.ssh/tools.pem root@123.56.89.187
Runner 服务器	101.200.136.200 (Jenkins 服务器)	ssh -i ~/.ssh/tools.pem root@101.200.136.200

API 访问

# Gitea API Token (仓库级)
GITEA_TOKEN="483a2b65219625ee382eb6d023cda39238c32e24"

# 通用请求格式
curl -s "https://gitea.pipexerp.com/api/v1/repos/pipexerp/<repo>/..." \
  -H "Authorization: token $GITEA_TOKEN"

常用 API

操作	方法	端点
创建 PR	POST	/repos/{owner}/{repo}/pulls
更新 PR	PATCH	/repos/{owner}/{repo}/pulls/{id}
列出 Runs	GET	/repos/{owner}/{repo}/actions/runs
Run 详情	GET	/repos/{owner}/{repo}/actions/runs/{id}
Job 详情	GET	/repos/{owner}/{repo}/actions/runs/{id}/jobs
手动触发 Workflow	POST	/repos/{owner}/{repo}/actions/workflows/{file}/dispatches body: {"ref":"main"}
获取 Runner Token	POST	/repos/{owner}/{repo}/actions/runners/registration-token
添加 Secret	PUT	/repos/{owner}/{repo}/actions/secrets/{name} body: {"data":"value"}
删除 Run（仅已完成）	DELETE	/repos/{owner}/{repo}/actions/runs/{id}

注意: Gitea 1.25 不支持通过 API cancel 正在排队/运行的 run。

仓库

仓库	地址	主分支
coolbuy-paas	pipexerp/coolbuy-paas	main
dotfiles	huangjun/dotfiles	main
claude-marketplace	huangjun/claude-marketplace	main

Actions Runners

主 Runner (lint/test/e2e)

项目	值
名称	jenkins-runner
配置	/opt/act_runner/config.yaml
Capacity	3
Labels	ubuntu-latest, ubuntu-22.04, ubuntu-20.04
进程	/usr/local/bin/act_runner daemon --config /opt/act_runner/config.yaml

Deploy Runner (staging 部署专用)

项目	值
名称	deploy-runner
配置	/opt/act_runner_deploy/config.yaml
Capacity	1
Labels	deploy:host
PID	/opt/act_runner_deploy/runner.pid
日志	/opt/act_runner_deploy/runner.log
启动	cd /opt/act_runner_deploy && nohup act_runner daemon --config config.yaml > runner.log 2>&1 &

注册新 Runner

# 1. 获取 registration token
curl -s -X POST "https://gitea.pipexerp.com/api/v1/repos/pipexerp/coolbuy-paas/actions/runners/registration-token" \
  -H "Authorization: token $GITEA_TOKEN"

# 2. SSH 到 runner 服务器
ssh -i ~/.ssh/tools.pem root@101.200.136.200

# 3. 创建目录和配置
mkdir -p /opt/act_runner_<name>
cat > /opt/act_runner_<name>/config.yaml << 'EOF'
log:
  level: info
runner:
  file: .runner
  capacity: 1
  timeout: 30m
  labels:
    - "<label>:host"    # host 模式用系统 shell
    # 或 "<label>:docker://image"  # docker 模式
cache:
  enabled: false
EOF

# 4. 注册
cd /opt/act_runner_<name>
act_runner register --instance https://gitea.pipexerp.com \
  --token <TOKEN> --name <NAME> --labels '<LABEL>:host' \
  --config config.yaml --no-interactive

# 5. 启动
nohup act_runner daemon --config config.yaml > runner.log 2>&1 &
echo $! > runner.pid

Runner 运维

# 检查 runner 状态
ssh -i ~/.ssh/tools.pem root@101.200.136.200 "ps aux | grep act_runner | grep -v grep"

# 查看 deploy runner 日志
ssh -i ~/.ssh/tools.pem root@101.200.136.200 "tail -20 /opt/act_runner_deploy/runner.log"

# 重启 deploy runner
ssh -i ~/.ssh/tools.pem root@101.200.136.200 "
kill \$(cat /opt/act_runner_deploy/runner.pid) 2>/dev/null
cd /opt/act_runner_deploy
nohup act_runner daemon --config config.yaml > runner.log 2>&1 &
echo \$! > runner.pid
"

Workflows (coolbuy-paas)

Workflow	触发	Runner	paths-ignore	用途
🚀 deploy-staging.yml	push → main	deploy	md, docs, .gitea, scripts, *_test.go	触发 Jenkins 部署到 staging
🔍 lint.yml	PR → main	ubuntu-latest	md, docs, .gitea, scripts	Go lint + ESLint auto-fix
🧪 unit-test.yml	PR → main	ubuntu-latest	md, docs, .gitea, scripts	4 个 Go 服务单元测试
🎭 e2e-tests.yml	schedule 12h	ubuntu-latest	—	Playwright E2E（仅定时）
📋 notify-aiproj.yml	PR merged	ubuntu-latest	—	同步需求状态到 ai-proj
📦 build.yaml	手动	ubuntu-latest	—	Docker 构建推 Hub

Workflow 编写规范

# 1. 名称加 emoji 前缀
name: "🚀 Deploy Staging"

# 2. 非代码变更加 paths-ignore
on:
  push:
    branches: [main]
    paths-ignore:
      - '*.md'
      - 'docs/**'
      - '.gitea/**'
      - 'scripts/**'

# 3. 加 concurrency 防重复
concurrency:
  group: deploy-staging
  cancel-in-progress: true

# 4. 仅定时的 workflow 加 event 守卫
jobs:
  e2e:
    if: github.event_name == 'schedule'

# 5. auto-fix 提交加 [skip ci]
git commit -m "style: auto-fix [skip ci]"

Checkout 模式（容器内）

Gitea Actions 不支持 actions/checkout，用原生 git：

- name: Checkout
  env:
    TOKEN: ${{ github.token }}
  run: |
    git config --global --add safe.directory "$(pwd)"
    git init
    git remote add origin "https://oauth2:${TOKEN}@gitea.pipexerp.com/${{ github.repository }}.git"
    git fetch origin "${{ github.event.pull_request.head.ref }}"
    git checkout -b pr-branch "origin/${{ github.event.pull_request.head.ref }}"
    git config user.name "CI Bot"
    git config user.email "ci@pipexerp.com"

Secrets 管理

当前 Secrets (coolbuy-paas 仓库级)

Secret	用途
JENKINS_USER	Jenkins API 用户名
JENKINS_TOKEN	Jenkins API Token
DOCKER_HUB_TOKEN	Docker Hub 推送
AI_PROJ_TOKEN	ai-proj API 认证

添加/更新 Secret

curl -s -X PUT \
  "https://gitea.pipexerp.com/api/v1/repos/pipexerp/coolbuy-paas/actions/secrets/<NAME>" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": "<VALUE>"}'

CI/CD 完整流程

PR → main
  ├── 🧪 unit-test.yml    (Go 服务测试)
  ├── 🔍 lint.yml          (auto-fix 格式)
  └── merge 后:
      ├── 📋 notify-aiproj.yml (需求状态 → testing)
      └── 🚀 deploy-staging.yml (Jenkins → staging)
          ├── ≥5 commits/2h → 立即部署
          └── <5 commits → 等3分钟 debounce

定时:
  └── 🎭 e2e-tests.yml (每12h Playwright)

手动:
  └── 📦 build.yaml (Docker 构建推 Hub)

生产部署:
  └── ./scripts/build-and-push.sh prod --deploy (触发 Jenkins)

本地 CLI 工具

tea CLI (Gitea 官方命令行)

tea 是 Gitea 官方 CLI 客户端，已配置好认证信息。

# 配置文件位置
~/Library/Application Support/tea/config.yml
# 或 ~/.config/tea/config.yml

# gitea-runs 脚本从 tea config 读取 url 和 token

gitea-runs (Actions 快捷命令)

位置: ~/.local/bin/gitea-runs

自动从 git remote 检测仓库，从 tea CLI 配置读取认证信息。

命令	说明
gitea-runs	列出最近 10 条 run
gitea-runs list [N]	列出最近 N 条 run
gitea-runs view <run_number>	查看 run 详情和 jobs
gitea-runs open [run_number]	在浏览器打开 run 页面
gitea-runs workflows	列出所有 workflow
gitea-runs dispatch <wf> [ref]	手动触发 workflow

# 示例
gitea-runs                    # 查看最近 runs
gitea-runs view 303           # 查看 run #303 详情
gitea-runs dispatch deploy-staging.yml main  # 手动触发部署
gitea-runs open               # 打开 Actions 页面

优先使用 gitea-runs 而非 curl API，更简洁且自动处理认证。

常见问题

问题	原因	解决
Run 一直 queued	Runner 被占满	等其他 job 完成，或加 runner
deploy 被 test 阻塞	共用 runner	用 runs-on: deploy 专属 runner
Workflow 被误触发	push 新 workflow 文件到 main	加 if: github.event_name == 'schedule' 守卫
auto-fix 无限循环	提交触发新 run	提交信息加 [skip ci]
API 无法 cancel run	Gitea 1.25 限制	网页手动取消，或等完成后 DELETE
date -d 报错	容器 date 不兼容	用 host 模式 runner，或兼容写法