Gitea Actions Runner 搭建指南为 Gitea 添加 CI/CD 自动化执行器Gitea 是一个轻量的自托管 Git 服务许多团队用它替代 GitHub 或 GitLab 来管理私有代码。从 Gitea 1.19 版本起官方加入了 Gitea Actions 支持语法兼容 GitHub Actions可以直接复用大量已有的 workflow 配置文件。但 Gitea Actions 本身只是调度系统真正执行 CI/CD 任务的是Actions Runner——一个独立运行的执行器程序监听 Gitea 下发的任务在本地环境执行构建、测试、部署等步骤执行完毕把日志和结果反馈给 Gitea。本文介绍如何用 Docker Compose Caddy 搭建 Gitea Actions Runner让你的私有 Gitea 拥有完整的 CI/CD 能力。服务器配置Runner 的资源消耗取决于 CI 任务的负载。如果需要运行编译构建、Docker 镜像构建等任务建议配置稍高。项目规格CPU2 核内存4GB硬盘40GB存储构建缓存和 Docker 镜像系统Ubuntu 22.04 / Debian 12推荐用雨云服务器 rainyun-com的 2 核 4GB 机型来运行 Gitea Actions Runner兼顾 CI 构建性能和价格。注册填2026off领 5 折。准备工作本教程假设你已有一个运行中的 Gitea 实例版本 1.19。如果还没有先搭建 Gitea可以参考其他 Gitea 部署教程。在 Gitea 中启用 Actions 功能编辑 Gitea 的配置文件app.ini在[actions]段落中启用[actions] ENABLED true重启 Gitea 后仓库设置中会出现Actions选项。获取 Runner 注册 Token有三种级别的 Runner对应不同的注册入口实例级 Runner站点管理员 → 管理面板 → Actions → Runner → 创建 Runner组织级 Runner组织设置 → Actions → Runner仓库级 Runner仓库设置 → Actions → Runner记下注册时显示的 Token格式类似ATXXXXXXXXXXXXXXXXXXXXXXXX。确保服务器已安装 Dockercurl-fsSLhttps://get.docker.com|shdocker--versiondockercompose versiondocker-compose.yml创建部署目录mkdir-p/opt/gitea-runnercd/opt/gitea-runner创建docker-compose.ymlversion:3.8services:gitea-runner:image:gitea/act_runner:latestcontainer_name:gitea-runnerenvironment:-GITEA_INSTANCE_URLhttps://git.example.com# 你的 Gitea 地址-GITEA_RUNNER_REGISTRATION_TOKENATXXXXXXXXXXXXXXXXXXXXXXXX# 注册 Token-GITEA_RUNNER_NAMEmy-runner-GITEA_RUNNER_LABELSubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://node:20-bullseye-CONFIG_FILE/config/config.yamlvolumes:-./config:/config-./data:/data-/var/run/docker.sock:/var/run/docker.sock# 允许 Runner 启动 Docker 容器restart:unless-stopped创建 Runner 配置文件mkdir-p/opt/gitea-runner/config创建/opt/gitea-runner/config/config.yamllog:level:inforunner:file:/data/.runnercapacity:2# 同时执行的最大任务数timeout:3h# 单个任务最长执行时间insecure:falsefetch_timeout:5sfetch_interval:2scache:enabled:truedir:/data/cachehost:port:0external_server:container:network:bridgeprivileged:falseoptions:workdir_parent:/data/workdirvalid_volumes:[]docker_host:host:workdir_parent:启动 Runnerdockercompose up-d配置说明验证 Runner 注册成功启动后查看日志确认连接到 Gitea 实例dockercompose logs-fgitea-runner成功时会看到类似输出INFO[0000] Starting runner... INFO[0001] Runner registered successfully with Gitea instance INFO[0001] Listening for tasks...在 Gitea 管理后台 → Actions → Runner 列表中也会看到 Runner 状态变为Online。Runner Labels 说明Labels 决定了 workflow 中runs-on指定的运行环境如何映射到实际执行器# workflow 文件中jobs:build:runs-on:ubuntu-latest# 对应 Runner 的 label默认 label 格式为标签名:执行方式ubuntu-latest:docker://node:20-bullseye # 使用 Docker 容器基于 node:20-bullseye 镜像 ubuntu-latest:host # 直接在宿主机执行不推荐安全隔离差并发任务数调整capacity参数控制同时运行的任务数量。2 核 4GB 内存建议设置为 2避免内存不足。如果 CI 任务较轻脚本为主无大型编译可以适当提高。Docker-in-DockerDinD支持如果 CI 任务需要构建 Docker 镜像已通过挂载/var/run/docker.sock支持。但需要注意任务容器内的 Docker 命令操作的是宿主机的 Docker 守护进程构建产生的镜像和容器会留在宿主机需要定期清理如需更强隔离可以改用 DinD 模式在容器内启动独立 Docker daemon使用方法编写 Workflow 文件在仓库根目录创建.gitea/workflows/ci.yml也可以用.github/workflows/ci.ymlGitea Actions 同样识别name:CIon:push:branches:[main,develop]pull_request:branches:[main]jobs:test:runs-on:ubuntu-lateststeps:-name:检出代码uses:actions/checkoutv4-name:设置 Node.js 环境uses:actions/setup-nodev4with:node-version:20cache:npm-name:安装依赖run:npm ci-name:运行测试run:npm test-name:构建run:npm run builddeploy:runs-on:ubuntu-latestneeds:testif:github.ref refs/heads/mainsteps:-name:检出代码uses:actions/checkoutv4-name:部署到服务器run:|echo 部署步骤...使用 Secrets在仓库设置 → Actions → Secrets 中添加敏感信息steps:-name:部署env:DEPLOY_KEY:${{secrets.DEPLOY_KEY}}SERVER_HOST:${{secrets.SERVER_HOST}}run:|echo $DEPLOY_KEY /tmp/deploy.pem chmod 600 /tmp/deploy.pem ssh -i /tmp/deploy.pem user$SERVER_HOST cd /app git pull docker compose up -dDocker 镜像构建示例name:Build and Push Docker Imageon:push:tags:-v*jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:构建 Docker 镜像run:|docker build -t myapp:${{ github.ref_name }} . docker tag myapp:${{ github.ref_name }} registry.example.com/myapp:${{ github.ref_name }}-name:推送到私有 Registryrun:|echo ${{ secrets.REGISTRY_PASSWORD }} | docker login registry.example.com -u ${{ secrets.REGISTRY_USERNAME }} --password-stdin docker push registry.example.com/myapp:${{ github.ref_name }}常见问题QRunner 已注册但任务一直排队不执行检查 Runner 的 label 是否与 workflow 中runs-on的值匹配。如果 workflow 写的是runs-on: ubuntu-latest但 Runner 没有ubuntu-latest这个 label任务会一直等待。查看并更新 Runner 的 label在 Gitea 管理后台找到对应 Runner编辑 label 列表。Q任务执行时提示 Docker 权限错误检查/var/run/docker.sock的权限确保 Runner 容器可以访问ls-la/var/run/docker.sock# 如果权限不够将当前用户加入 docker 组sudousermod-aGdocker$USERQ构建缓存如何利用Gitea Actions 支持actions/cacheAction可以缓存 npm、Maven、pip 等依赖目录加速后续构建-name:缓存 npm 依赖uses:actions/cachev3with:path:~/.npmkey:${{runner.os}}-npm-${{hashFiles(**/package-lock.json)}}restore-keys:|${{ runner.os }}-npm-Q如何清理积累的 Docker 镜像和容器添加定时清理任务# 编辑 crontabcrontab-e# 每周日凌晨清理未使用的 Docker 资源03* *0dockersystem prune-fGitea Actions Runner 搭建完成后你的私有 Git 服务就拥有了完整的 CI/CD 流水线能力workflow 文件语法与 GitHub Actions 高度兼容迁移成本极低。
Gitea Actions Runner 搭建指南：为 Gitea 添加 CI/CD 自动化执行器
Gitea Actions Runner 搭建指南为 Gitea 添加 CI/CD 自动化执行器Gitea 是一个轻量的自托管 Git 服务许多团队用它替代 GitHub 或 GitLab 来管理私有代码。从 Gitea 1.19 版本起官方加入了 Gitea Actions 支持语法兼容 GitHub Actions可以直接复用大量已有的 workflow 配置文件。但 Gitea Actions 本身只是调度系统真正执行 CI/CD 任务的是Actions Runner——一个独立运行的执行器程序监听 Gitea 下发的任务在本地环境执行构建、测试、部署等步骤执行完毕把日志和结果反馈给 Gitea。本文介绍如何用 Docker Compose Caddy 搭建 Gitea Actions Runner让你的私有 Gitea 拥有完整的 CI/CD 能力。服务器配置Runner 的资源消耗取决于 CI 任务的负载。如果需要运行编译构建、Docker 镜像构建等任务建议配置稍高。项目规格CPU2 核内存4GB硬盘40GB存储构建缓存和 Docker 镜像系统Ubuntu 22.04 / Debian 12推荐用雨云服务器 rainyun-com的 2 核 4GB 机型来运行 Gitea Actions Runner兼顾 CI 构建性能和价格。注册填2026off领 5 折。准备工作本教程假设你已有一个运行中的 Gitea 实例版本 1.19。如果还没有先搭建 Gitea可以参考其他 Gitea 部署教程。在 Gitea 中启用 Actions 功能编辑 Gitea 的配置文件app.ini在[actions]段落中启用[actions] ENABLED true重启 Gitea 后仓库设置中会出现Actions选项。获取 Runner 注册 Token有三种级别的 Runner对应不同的注册入口实例级 Runner站点管理员 → 管理面板 → Actions → Runner → 创建 Runner组织级 Runner组织设置 → Actions → Runner仓库级 Runner仓库设置 → Actions → Runner记下注册时显示的 Token格式类似ATXXXXXXXXXXXXXXXXXXXXXXXX。确保服务器已安装 Dockercurl-fsSLhttps://get.docker.com|shdocker--versiondockercompose versiondocker-compose.yml创建部署目录mkdir-p/opt/gitea-runnercd/opt/gitea-runner创建docker-compose.ymlversion:3.8services:gitea-runner:image:gitea/act_runner:latestcontainer_name:gitea-runnerenvironment:-GITEA_INSTANCE_URLhttps://git.example.com# 你的 Gitea 地址-GITEA_RUNNER_REGISTRATION_TOKENATXXXXXXXXXXXXXXXXXXXXXXXX# 注册 Token-GITEA_RUNNER_NAMEmy-runner-GITEA_RUNNER_LABELSubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://node:20-bullseye-CONFIG_FILE/config/config.yamlvolumes:-./config:/config-./data:/data-/var/run/docker.sock:/var/run/docker.sock# 允许 Runner 启动 Docker 容器restart:unless-stopped创建 Runner 配置文件mkdir-p/opt/gitea-runner/config创建/opt/gitea-runner/config/config.yamllog:level:inforunner:file:/data/.runnercapacity:2# 同时执行的最大任务数timeout:3h# 单个任务最长执行时间insecure:falsefetch_timeout:5sfetch_interval:2scache:enabled:truedir:/data/cachehost:port:0external_server:container:network:bridgeprivileged:falseoptions:workdir_parent:/data/workdirvalid_volumes:[]docker_host:host:workdir_parent:启动 Runnerdockercompose up-d配置说明验证 Runner 注册成功启动后查看日志确认连接到 Gitea 实例dockercompose logs-fgitea-runner成功时会看到类似输出INFO[0000] Starting runner... INFO[0001] Runner registered successfully with Gitea instance INFO[0001] Listening for tasks...在 Gitea 管理后台 → Actions → Runner 列表中也会看到 Runner 状态变为Online。Runner Labels 说明Labels 决定了 workflow 中runs-on指定的运行环境如何映射到实际执行器# workflow 文件中jobs:build:runs-on:ubuntu-latest# 对应 Runner 的 label默认 label 格式为标签名:执行方式ubuntu-latest:docker://node:20-bullseye # 使用 Docker 容器基于 node:20-bullseye 镜像 ubuntu-latest:host # 直接在宿主机执行不推荐安全隔离差并发任务数调整capacity参数控制同时运行的任务数量。2 核 4GB 内存建议设置为 2避免内存不足。如果 CI 任务较轻脚本为主无大型编译可以适当提高。Docker-in-DockerDinD支持如果 CI 任务需要构建 Docker 镜像已通过挂载/var/run/docker.sock支持。但需要注意任务容器内的 Docker 命令操作的是宿主机的 Docker 守护进程构建产生的镜像和容器会留在宿主机需要定期清理如需更强隔离可以改用 DinD 模式在容器内启动独立 Docker daemon使用方法编写 Workflow 文件在仓库根目录创建.gitea/workflows/ci.yml也可以用.github/workflows/ci.ymlGitea Actions 同样识别name:CIon:push:branches:[main,develop]pull_request:branches:[main]jobs:test:runs-on:ubuntu-lateststeps:-name:检出代码uses:actions/checkoutv4-name:设置 Node.js 环境uses:actions/setup-nodev4with:node-version:20cache:npm-name:安装依赖run:npm ci-name:运行测试run:npm test-name:构建run:npm run builddeploy:runs-on:ubuntu-latestneeds:testif:github.ref refs/heads/mainsteps:-name:检出代码uses:actions/checkoutv4-name:部署到服务器run:|echo 部署步骤...使用 Secrets在仓库设置 → Actions → Secrets 中添加敏感信息steps:-name:部署env:DEPLOY_KEY:${{secrets.DEPLOY_KEY}}SERVER_HOST:${{secrets.SERVER_HOST}}run:|echo $DEPLOY_KEY /tmp/deploy.pem chmod 600 /tmp/deploy.pem ssh -i /tmp/deploy.pem user$SERVER_HOST cd /app git pull docker compose up -dDocker 镜像构建示例name:Build and Push Docker Imageon:push:tags:-v*jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:构建 Docker 镜像run:|docker build -t myapp:${{ github.ref_name }} . docker tag myapp:${{ github.ref_name }} registry.example.com/myapp:${{ github.ref_name }}-name:推送到私有 Registryrun:|echo ${{ secrets.REGISTRY_PASSWORD }} | docker login registry.example.com -u ${{ secrets.REGISTRY_USERNAME }} --password-stdin docker push registry.example.com/myapp:${{ github.ref_name }}常见问题QRunner 已注册但任务一直排队不执行检查 Runner 的 label 是否与 workflow 中runs-on的值匹配。如果 workflow 写的是runs-on: ubuntu-latest但 Runner 没有ubuntu-latest这个 label任务会一直等待。查看并更新 Runner 的 label在 Gitea 管理后台找到对应 Runner编辑 label 列表。Q任务执行时提示 Docker 权限错误检查/var/run/docker.sock的权限确保 Runner 容器可以访问ls-la/var/run/docker.sock# 如果权限不够将当前用户加入 docker 组sudousermod-aGdocker$USERQ构建缓存如何利用Gitea Actions 支持actions/cacheAction可以缓存 npm、Maven、pip 等依赖目录加速后续构建-name:缓存 npm 依赖uses:actions/cachev3with:path:~/.npmkey:${{runner.os}}-npm-${{hashFiles(**/package-lock.json)}}restore-keys:|${{ runner.os }}-npm-Q如何清理积累的 Docker 镜像和容器添加定时清理任务# 编辑 crontabcrontab-e# 每周日凌晨清理未使用的 Docker 资源03* *0dockersystem prune-fGitea Actions Runner 搭建完成后你的私有 Git 服务就拥有了完整的 CI/CD 流水线能力workflow 文件语法与 GitHub Actions 高度兼容迁移成本极低。
