opencode/skill/gitea/workflow-generator.md

Gitea Workflow 生成器

根据项目类型自动生成 CI/CD workflow 文件。

概述

Gitea Actions 使用 GitHub Actions 兼容的 workflow 语法，定义在 .gitea/workflows/*.yml 文件中。

本 skill 提供：

• 自动检测项目类型
• 根据类型生成适配的 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

自动生成流程

步骤 1: 检测项目类型

当用户说"为我的项目生成 workflow"时，AI 会自动检测项目类型：

# Go 项目特征
if [ -f "go.mod" ] || [ -f "main.go" ]; then
  project_type="go"
fi

# Node.js 项目特征
if [ -f "package.json" ]; then
  project_type="nodejs"
  
  # 细分类型
  if grep -q "\"react\"" package.json; then
    framework="react"
  elif grep -q "\"vue\"" package.json; then
    framework="vue"
  elif grep -q "\"vite\"" package.json; then
    framework="vite"
  fi
fi

# Android 项目特征
if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
  if [ -d "app/src/main/java" ] || [ -d "app/src/main/kotlin" ]; then
    project_type="android"
  fi
fi

# 微信小程序特征
if [ -f "project.config.json" ] && [ -f "app.json" ]; then
  project_type="wechat-miniprogram"
fi

步骤 2: 提示用户确认

检测到项目类型: Go 后端服务
服务目录: ./backend
是否正确? [Y/n]

步骤 3: 收集项目信息

根据项目类型，收集必要信息：

Go 项目：

• 服务目录（如 ./backend）
• 服务名称（如 api-server）
• 是否需要 Docker 构建
• Docker Registry 地址

Node.js 项目：

• 项目目录
• 包管理器（npm/pnpm/yarn）
• 构建命令
• 输出目录

Android 项目：

• 模块名称（如 app）
• 构建类型（release/debug）
• 签名配置

微信小程序：

• 项目目录
• 版本号规则
• 上传配置

步骤 4: 选择 Runner

请选择 Runner:
  1) darwin-arm64 (macOS ARM64)
  2) ubuntu-latest (Docker)
  3) 自定义

[1]:

步骤 5: 生成 Workflow 文件

基于模板生成 workflow，自动替换变量：

name: Backend Service - Build & Publish

on:
  push:
    paths:
      - 'backend/**'                    # 自动填充：项目目录
      - '.gitea/workflows/backend.yml'
    tags:
      - 'backend-*'                     # 自动填充：服务前缀

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  SERVICE_PREFIX: backend               # 自动填充：服务名称
  SERVICE_DIR: backend                  # 自动填充：服务目录
  GOPROXY: https://goproxy.cn,direct

jobs:
  build-and-publish:
    name: Build & Publish
    runs-on: darwin-arm64               # 自动填充：Runner
    # ... 其余配置

步骤 6: 创建文件

# 创建 .gitea/workflows 目录
mkdir -p .gitea/workflows

# 写入 workflow 文件
cat > .gitea/workflows/backend.yml << 'EOF'
[生成的 workflow 内容]
EOF

echo "✓ Workflow 已生成: .gitea/workflows/backend.yml"

步骤 7: 提示配置 Secrets

根据 workflow 需求，提示用户配置 Secrets：

需要配置以下 Secrets:
  - REGISTRY_PASSWORD: Docker Registry 密码
  - RELEASE_TOKEN: Gitea API Token（创建 Release 用）

配置方法:
  1. 在 Gitea 中打开仓库设置
  2. 进入 Settings → Secrets → Actions
  3. 添加上述 Secrets

或使用 API:
  source ~/.config/gitea/config.env
  echo -n "password" | base64 | xargs -I {} \
    curl -X PUT \
    -H "Authorization: token $GITEA_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"data":"{}"}' \
    "$GITEA_URL/api/v1/repos/owner/repo/actions/secrets/REGISTRY_PASSWORD"

Workflow 基础结构

完整骨架

name: Service Name - Build & Publish

# 触发条件
on:
  push:
    paths:
      - 'service-dir/**'
      - '.gitea/workflows/this-workflow.yml'
    tags:
      - 'service-prefix-*'

# 并发控制
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# 环境变量
env:
  SERVICE_PREFIX: service-name
  SERVICE_DIR: service-dir

jobs:
  build:
    name: Build
    runs-on: darwin-arm64
    permissions:
      contents: read
      packages: write
    
    outputs:
      version: ${{ steps.vars.outputs.version }}
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      # 项目特定的构建步骤
      
  release:
    name: Create Release
    runs-on: darwin-arm64
    needs: build
    if: startsWith(github.ref, 'refs/tags/service-prefix-')
    steps:
      # Release 步骤

触发条件配置

常用触发模式

on:
  # 分支推送
  push:
    branches: [main, develop]
  
  # 路径过滤（推荐：仅相关文件变更时触发）
  push:
    paths:
      - 'src/**'
      - '*.yml'
  
  # Tag 推送（用于 Release）
  push:
    tags:
      - 'v*'
      - 'service-*'
  
  # Pull Request
  pull_request:
    branches: [main]
  
  # 手动触发
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        default: 'staging'
  
  # 定时触发
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

并发控制

避免同一分支的多个 workflow 同时运行：

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true  # 取消旧的运行

通用组件

Checkout

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0          # 完整历史，用于 git describe
    # fetch-depth: 1        # 仅最新提交，加快速度

变量设置

- name: Set variables
  id: vars
  run: |
    git_tag=$(git describe --tags --abbrev=0 --always)
    registry=$(echo ${{ github.server_url }} | cut -d '/' -f 3)
    
    # 写入环境变量（当前 job 可用）
    {
      echo "git_tag=${git_tag}"
      echo "registry=${registry}"
    } >> $GITHUB_ENV
    
    # 写入输出（其他 job 可用）
    echo "version=${git_tag}" >> $GITHUB_OUTPUT

Cache Action

- name: Cache dependencies
  uses: https://github.com/actions/cache@v3
  with:
    path: |
      ~/.cache/directory
      ./node_modules
    key: cache-name-${{ hashFiles('**/lockfile') }}
    restore-keys: cache-name-

各语言缓存路径：

语言	缓存路径	Key 文件
Go	~/go/pkg/mod, ~/.cache/go-build	go.mod, go.sum
Node.js (pnpm)	~/.pnpm-store, node_modules	pnpm-lock.yaml
Node.js (npm)	~/.npm, node_modules	package-lock.json
Gradle	~/.gradle/caches, ~/.gradle/wrapper	*.gradle*, gradle-wrapper.properties

Docker 构建推送

- name: Docker - Login
  uses: docker/login-action@v3
  with:
    registry: ${{ env.registry }}
    username: ${{ vars.REGISTRY_USERNAME }}
    password: ${{ secrets.REGISTRY_PASSWORD }}

- name: Docker - Setup Buildx
  uses: docker/setup-buildx-action@v3

- name: Docker - Build & Push
  uses: docker/build-push-action@v6
  with:
    context: ./service-dir
    file: ./service-dir/Dockerfile
    push: true
    platforms: linux/amd64
    tags: |
      ${{ env.registry }}/owner/image:latest
      ${{ env.registry }}/owner/image:${{ env.git_tag }}
    cache-from: type=registry,ref=image:buildcache
    cache-to: type=registry,ref=image:buildcache,mode=max

Artifact 上传/下载

# 上传
- name: Upload artifact
  uses: actions/upload-artifact@v3
  with:
    name: build-artifact
    path: dist/

# 下载（另一个 job）
- name: Download artifact
  uses: actions/download-artifact@v3
  with:
    name: build-artifact
    path: dist/

通知 Webhook

- name: Notify
  if: always()
  continue-on-error: true
  env:
    WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
  run: |
    status="${{ job.status }}"
    [ "$status" = "success" ] && text="Build Success" || text="Build Failed"
    
    curl -s -H "Content-Type: application/json" -X POST \
      -d "{\"msg_type\":\"text\",\"content\":{\"text\":\"${{ env.SERVICE_PREFIX }} ${text}\"}}" \
      "$WEBHOOK_URL"

Release 创建（Gitea API）

- name: Create Release
  env:
    GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN }}
  run: |
    git_tag=$(git describe --tags --abbrev=0)
    api_url="${{ github.server_url }}/api/v1"
    repo="${{ github.repository }}"
    
    # 创建 Release
    release_id=$(curl -s -X POST \
      -H "Authorization: token $GITEA_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"tag_name\":\"${git_tag}\",\"name\":\"Release ${git_tag}\"}" \
      "${api_url}/repos/${repo}/releases" | jq -r '.id')
    
    # 上传附件
    curl -s -X POST \
      -H "Authorization: token $GITEA_TOKEN" \
      -F "attachment=@dist/artifact.zip" \
      "${api_url}/repos/${repo}/releases/${release_id}/assets"

Secrets 配置

通用 Secrets

Secret	用途	适用项目
REGISTRY_PASSWORD	Docker Registry 密码	需要 Docker 发布的项目
RELEASE_TOKEN	Gitea API 令牌	需要创建 Release 的项目

安全最佳实践

1. 不要在日志中打印 secrets
2. 使用 vars. 存储非敏感变量（如用户名、URL）
3. secrets 仅用于敏感信息（如密码、密钥）
4. 定期轮换密钥

配置 Secrets

方法 1: 通过 Gitea UI

1. 打开仓库 → Settings → Secrets → Actions
2. 点击 "Add Secret"
3. 输入 Name 和 Value
4. 保存

方法 2: 通过 API

source ~/.config/gitea/config.env

secret_name="REGISTRY_PASSWORD"
secret_value="my-password"

# Base64 编码
encoded=$(echo -n "$secret_value" | base64)

# 调用 API
curl -X PUT \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"${encoded}\"}" \
  "$GITEA_URL/api/v1/repos/owner/repo/actions/secrets/$secret_name"

最佳实践

1. 路径过滤

仅相关文件变更时触发，避免无关构建：

on:
  push:
    paths:
      - 'backend/**'
      - '.gitea/workflows/backend.yml'

2. Tag 命名规范

使用前缀区分不同服务：

git tag backend-1.0.0 && git push origin backend-1.0.0
git tag frontend-1.0.0 && git push origin frontend-1.0.0
git tag android-1.0.0 && git push origin android-1.0.0

3. Job 输出传递

jobs:
  build:
    outputs:
      version: ${{ steps.vars.outputs.version }}
  
  deploy:
    needs: build
    env:
      VERSION: ${{ needs.build.outputs.version }}

4. 条件执行

# 仅 Tag 推送时执行
if: startsWith(github.ref, 'refs/tags/')

# 仅主分支执行
if: github.ref == 'refs/heads/main'

# 始终执行（用于通知）
if: always()

5. 使用缓存加速构建

合理使用缓存可以显著减少构建时间：

# Go 项目
- name: Cache Go modules
  uses: https://github.com/actions/cache@v3
  with:
    path: |
      ~/go/pkg/mod
      ~/.cache/go-build
    key: go-${{ hashFiles('**/go.sum') }}

# Node.js 项目
- name: Cache pnpm store
  uses: https://github.com/actions/cache@v3
  with:
    path: ~/.pnpm-store
    key: pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}

项目特定模板

Go 后端服务

详见：Go 后端模板

特点：

• 支持 monorepo 和 polyrepo
• Docker 多阶段构建
• 自动版本管理
• Release 创建和附件上传

Node.js 前端应用

详见：Node.js 前端模板

特点：

• pnpm/npm/yarn 支持
• 依赖缓存优化
• 静态资源构建
• Docker 部署

Android 应用

详见：Android 应用模板

特点：

• Gradle 缓存优化
• 多 flavor 支持
• 签名配置
• APK/AAB 生成

微信小程序

详见：微信小程序模板

特点：

• 自动版本号管理
• miniprogram-ci 集成
• 预览/上传自动化
• 体验版分发

快速参考

任务	命令/语法
获取 git tag	git describe --tags --abbrev=0 --always
提取 registry	echo ${{ github.server_url }} | cut -d '/' -f 3
设置环境变量	echo "KEY=value" >> $GITHUB_ENV
设置输出	echo "key=value" >> $GITHUB_OUTPUT
计算哈希	sha256sum file1 file2 | sha256sum | head -c 16

使用方式

1. 自然语言触发：

   用户: 为我的项目生成 workflow
   用户: 创建 CI/CD 配置
   用户: 添加自动化构建
   

2. AI 自动检测项目类型

3. 填充项目特定信息

4. 生成 workflow 文件：.gitea/workflows/*.yml

5. 配置 Secrets（如需要）

6. 推送代码触发：

   git add .gitea/workflows
   git commit -m "Add CI/CD workflow"
   git push origin main
   

相关资源

• Gitea Actions 文档
• GitHub Actions Workflow 语法
• 环境配置指南
• Runner 管理

版本

• 文档版本: 1.0
• 最后更新: 2026-01-12
• 整合内容: gitea-workflow skill 的所有模板