Gitea Actions CI/CD 教程

Gitea Actions 是 Gitea 内置的 CI/CD 系统，兼容 GitHub Actions 的 Workflow 语法，可以直接使用大量现有的 GitHub Actions。通过 Gitea Actions，你可以在搬瓦工 VPS 上实现代码提交后自动构建、测试和部署，无需依赖外部 CI/CD 服务。本教程假设你已经安装了 Gitea。

一、启用 Gitea Actions

编辑 Gitea 配置文件 app.ini，启用 Actions 功能：

# 编辑 Gitea 配置
cat >> /opt/gitea/data/gitea/conf/app.ini <<'EOF'

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = github
EOF

# 重启 Gitea
docker restart gitea

二、安装 Act Runner

Gitea Actions 需要 Runner 来执行工作流任务。Act Runner 是 Gitea 官方的 Runner 实现：

2.1 下载 Act Runner

wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64 -O /usr/local/bin/act_runner
chmod +x /usr/local/bin/act_runner
act_runner --version

2.2 注册 Runner

在 Gitea 管理界面中获取 Runner 注册令牌：进入"站点管理" -> "Runners"，复制注册令牌。然后注册 Runner：

act_runner register \
  --instance https://git.your-domain.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name vps-runner \
  --labels ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://ubuntu:22.04

2.3 使用 systemd 管理 Runner

cat > /etc/systemd/system/act-runner.service <<'EOF'
[Unit]
Description=Gitea Act Runner
After=network.target docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/act-runner
ExecStart=/usr/local/bin/act_runner daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

mkdir -p /opt/act-runner
cp .runner /opt/act-runner/
systemctl daemon-reload
systemctl enable act-runner
systemctl start act-runner

三、编写 Workflow

在 Git 仓库中创建 .gitea/workflows/ 目录，添加 YAML 工作流文件。

3.1 基础构建流程

# .gitea/workflows/build.yml
name: Build and Test
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build project
        run: npm run build

3.2 Docker 镜像构建与推送

# .gitea/workflows/docker.yml
name: Build Docker Image
on:
  push:
    tags: ['v*']

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: git.your-domain.com
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_PASS }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: git.your-domain.com/${{ github.repository }}:${{ github.ref_name }}

3.3 自动部署到服务器

# .gitea/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          script: |
            cd /opt/myapp
            git pull origin main
            npm ci --production
            pm2 restart myapp

四、管理 Secrets

在 Gitea 仓库设置的"Secrets"页面中添加敏感变量，在 Workflow 中通过 ${{ secrets.NAME }} 引用。常用 Secrets 包括：

部署服务器的 SSH 密钥。
容器镜像仓库的登录凭据。
API Token 和密码。

五、使用 Docker Runner（推荐）

mkdir -p /opt/act-runner && cd /opt/act-runner

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  runner:
    image: gitea/act_runner:latest
    container_name: act-runner
    restart: always
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - GITEA_INSTANCE_URL=https://git.your-domain.com
      - GITEA_RUNNER_REGISTRATION_TOKEN=YOUR_TOKEN
      - GITEA_RUNNER_NAME=docker-runner
EOF

docker compose up -d

六、多语言项目示例

6.1 Go 项目

name: Go CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go build ./...
      - run: go test ./...

6.2 Python 项目

name: Python CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: pytest

七、常见问题

Runner 显示离线

检查 Runner 服务是否正常运行：

systemctl status act-runner
journalctl -u act-runner -f

Action 下载失败

确保 VPS 能正常访问 GitHub（Gitea Actions 默认从 GitHub 下载 Action）。

总结

Gitea Actions 提供了与 GitHub Actions 兼容的 CI/CD 能力，让你在搬瓦工 VPS 上拥有完整的代码托管和自动化流水线。结合 Act Runner 可以实现高效的持续集成与部署。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关教程：Act Runner 配置、Woodpecker 集成。