Files

Voson ae0cb58a94 chore: 初始化 opencode 配置

2026-01-12 17:39:49 +08:00

8.6 KiB

Raw Blame History

name, description

name	description
gitea-workflow	Gitea Actions Workflow foundation and templates for various project types with CI/CD best practices

Gitea Actions Workflow Skill

Gitea Actions workflow 基础知识和项目模板指南，兼容 GitHub Actions 语法。

概述

Gitea Actions workflows 定义在 .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

Workflow 基础结构

文件位置

project/
├── .gitea/
│   └── workflows/
│       ├── backend.yml
│       ├── frontend.yml
│       └── ...
└── ...

骨架模板

name: Service Name - Build & Publish

on:
  push:
    paths:
      - 'service-dir/**'                    # 仅相关目录变更时触发
      - '.gitea/workflows/this-workflow.yml'
    tags:
      - 'service-prefix-*'                  # Tag 触发 Release

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

env:
  SERVICE_PREFIX: service-name              # 服务标识

jobs:
  build:
    name: Build
    runs-on: darwin-arm64                   # Runner 标签
    permissions:
      contents: read
      packages: write
    
    outputs:
      version: ${{ steps.vars.outputs.version }}
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0                    # 完整历史（用于 git describe）

      # ... 构建步骤

  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 点

并发控制

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`

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/

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 }}/${{ github.repository_owner }}/image:latest
      ${{ env.registry }}/${{ github.repository_owner }}/image:${{ env.git_tag }}
    cache-from: type=registry,ref=image:buildcache
    cache-to: type=registry,ref=image:buildcache,mode=max

通知 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 的项目

项目特定 Secrets

参考各项目类型子文档。

安全最佳实践

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

最佳实践

1. 路径过滤

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

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

2. Tag 命名规范

使用前缀区分不同服务：

git tag server-1.0.0 && git push origin server-1.0.0
git tag web-1.0.0 && git push origin web-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()

快速参考

任务	命令/语法
获取 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`

使用方式

选择项目类型：参考上方索引表，选择对应的子文档
复制骨架模板：将模板复制到 .gitea/workflows/
填充构建逻辑：根据项目需求填充 # 用户自定义 部分
配置 Secrets：在 Gitea 中配置所需的 Secrets
推送触发：推送代码或 Tag 触发 workflow

版本

Skill Version: 2.0
Last Updated: 2026-01-12
Structure: 主文档 + 4 个项目类型子文档

8.6 KiB Raw Blame History Unescape Escape