Gitea内置CI/CD体验

发表于 2022-12-15 更新于 2026-04-20

本文是 Gitea 官方对内置 CI/CD 系统 Gitea Actions 的详细介绍与早期尝鲜指南。Gitea Actions 旨在提供一个与代码仓库深度集成、易于使用的 CI/CD 解决方案，兼容 GitHub Actions 的工作流格式和生态。

一、概述与背景

1.1 什么是 Gitea Actions？

Gitea Actions 是 Gitea 自 1.19.0 版本起引入的内置持续集成和持续交付 (CI/CD) 平台。它允许用户在代码仓库中通过 YAML 文件定义工作流，自动化执行构建、测试、部署等任务。

核心目标：降低 DevOps 工具链的搭建和维护门槛，为 Gitea 用户提供开箱即用、与代码管理一体化的 CI/CD 体验。

1.2 设计理念与兼容性

Gitea Actions 的设计借鉴了 GitHub Actions 的成功经验：

代码即配置：工作流文件 (.gitea/workflows/*.yaml 或 .github/workflows/*.yaml) 存储在仓库中，与代码版本管理同步。
兼容 GitHub Actions：高度兼容 GitHub Actions 的 YAML 工作流语法、上下文变量和事件触发器。
复用生态：兼容大部分 GitHub Marketplace 中的 Actions 插件，极大地扩展了其能力。

1.3 Gitea 现有的 DevOps 生态

在 Gitea Actions 出现之前，社区已为 Gitea 适配了众多优秀的第三方 CI/CD 工具，例如 Drone、Jenkins、Woodpecker、Agola 等。Gitea Actions 并非要取代它们，而是为希望获得更简单、更集成化体验的用户提供一个新的选择。

二、 Gitea Actions 架构与特性

2.1 系统架构

Gitea Actions 系统由三部分组成：

**Gitea 主程序 (Server)**：负责工作流的管理、任务调度、状态跟踪和结果展示。它实现了 Actions 协议。
**Act Runner (客户端)**：独立的工作流执行器。它从 Gitea 服务器拉取任务，在隔离的环境（通常是 Docker 容器）中执行工作流步骤，并将日志和结果回传。
Actions 协议：定义了 Server 与 Runner 之间的通信规范，确保二者可以独立开发和部署。

2.2 主要特性

内置集成：无需额外安装复杂的 CI/CD 服务器，在 Gitea 管理界面即可完成全部配置。
基于 Docker：Runner 使用 Docker 容器作为任务执行环境，保证了环境的一致性和隔离性。
多 Runner 支持：可以注册多个 Runner 到同一 Gitea 实例，并为其分配不同的标签（如 ubuntu-latest, self-hosted），实现任务的分发与负载均衡。
Web 管理界面：提供清晰的工作流运行历史、实时日志查看和 Runner 状态监控。

2.3 管理界面预览

Runner 管理 (/admin/runners)：系统管理员可以在此页面查看、注册、编辑和删除 Runner。
仓库工作流列表：在仓库顶部导航栏点击 Actions，可以查看该仓库的所有工作流运行记录。
工作流执行详情：点击任意一次运行记录，可以查看详细的、实时更新的执行日志。

三、尝鲜部署指南 (基于早期开发版)

注意：本文撰写时（2022年12月）Gitea Actions 尚处于开发阶段。目前（2025年）Gitea Actions 已是稳定功能。以下步骤保留了历史原貌，对于理解架构仍有价值，但实际部署请直接使用 Gitea 1.19.0 及以上版本 和对应的 **稳定版 act_runner**。

3.1 环境准备

内存：至少 4GB（用于编译）。
Docker：Runner 执行任务需要调用 Docker。

3.2 编译并启用 Gitea (Server)

克隆开发分支代码（当时）：

1 2	git clone https://github.com/wolfogre/gitea.git --branch=feature/bots cd gitea

编译 Gitea（支持 SQLite）：

1	TAGS="bindata sqlite sqlite_unlock_notify" make build

首次运行并生成配置：
1
./gitea web
访问 http://localhost:3000 完成初始化安装，这会在 ./custom/conf/app.ini 生成配置文件。
启用 Actions 功能：编辑 app.ini，添加或修改：
1
2
[actions]
ENABLED = true
重启 Gitea：
1
./gitea web

3.3 配置与启动 Act Runner

**编译 act_runner**：

1
2
3

git clone https://gitea.com/gitea/act_runner.git
cd act_runner
make build

注册 Runner 到 Gitea：
- 获取注册令牌：以管理员身份登录 Gitea，进入 管理后台 -> Actions -> Runner，点击“注册新 Runner”并复制令牌。
- 执行注册命令：
  1
  ./act_runner register --no-interactive --instance http://<你的Gitea地址> --token <复制的令牌> --labels ubuntu-latest:docker://node:16-bullseye
  - --labels：为此 Runner 设置标签，工作流中 runs-on: ubuntu-latest 的任务会分配给它。
启动 Runner：
1
./act_runner daemon

3.4 为仓库启用 Actions 并创建第一个工作流

仓库设置：进入任意仓库的 设置 -> 通用，勾选 启用 Actions 并保存。
创建工作流文件：在仓库根目录创建 .gitea/workflows/demo.yaml（或 .github/workflows/demo.yaml）。

编写示例工作流：将以下内容保存到上述文件：

name: Gitea Actions Demo
on: [push]
jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 本次任务由 ${{ gitea.event_name }} 事件触发。"
      - run: echo "🐧 任务正在 Gitea 提供的 ${{ runner.os }} 服务器上运行！"
      - name: 检出代码
        uses: actions/checkout@v3
      - name: 列出文件
        run: |
          ls -la ${{ gitea.workspace }}
      - run: echo "✅ 工作流执行完成。"

触发与查看：提交并推送这个工作流文件到仓库。Gitea 会自动检测到推送事件，触发工作流执行。随后在仓库的 Actions 标签页即可看到运行记录和详细日志。

四、总结与后续发展

Gitea Actions 的推出，标志着 Gitea 从一个纯粹的代码托管平台，向一体化 DevOps 平台迈出了坚实的一步。它通过复用成熟的 GitHub Actions 生态，极大地降低了用户的学习和使用成本。

重要更新：

稳定版本：Gitea Actions 功能已于 Gitea 1.19.0 版本正式发布。
官方文档：请参阅最新的官方文档以获取稳定的安装、配置和使用指南：Gitea Actions 文档。
**act_runner**：请从官方仓库 gitea/act_runner 获取最新的稳定版本。

对于追求简单、集成化 CI/CD 体验的团队和个人，Gitea Actions 是一个非常值得尝试的选择。它让在自托管环境中享受类 GitHub Actions 的流畅体验成为可能。

提示：生产环境部署时，请务必参考官方稳定版文档，并关注安全最佳实践，如配置独立的 Runner 用户、限制 Docker 权限等。

一、 概述与背景