---
name: gitea-workflow
description: 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](./go-backend.md) | API 服务、微服务、CLI 工具 |
| Node.js 前端 | [nodejs-frontend.md](./nodejs-frontend.md) | React/Vue/Vite/Next.js |
| Android 应用 | [android-app.md](./android-app.md) | Kotlin/Java/Jetpack Compose |
| 微信小程序 | [wechat-miniprogram.md](./wechat-miniprogram.md) | 微信小程序 CI/CD |

---

## Workflow 基础结构

### 文件位置

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

### 骨架模板

```yaml
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 步骤
```

---

## 触发条件

### 常用触发模式

```yaml
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 点
```

### 并发控制

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

---

## 通用组件

### Checkout

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

### 变量设置

```yaml
- 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

```yaml
- 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 上传/下载

```yaml
# 上传
- 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 构建推送

```yaml
- 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

```yaml
- 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）

```yaml
- 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

参考各项目类型子文档。

### 安全最佳实践

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

---

## 最佳实践

### 1. 路径过滤

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

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

### 2. Tag 命名规范

使用前缀区分不同服务：

```bash
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 输出传递

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

### 4. 条件执行

```yaml
# 仅 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` |

---

## 使用方式

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

---

## 版本

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