从零开始打造自托管 CI/CD：Gitea Actions 安装、配置与使用全攻略

言简意赅的讲解Gitea Actions解决的痛点

一、什么是 Gitea Actions？为什么使用 Gitea Actions？

1.1 Gitea Actions 简介

Gitea Actions 是 Gitea 生态内的 CI/CD 解决方案，它与 GitHub Actions 类似，可以让开发者在代码库（Repository）内直接编写工作流（Workflow），实现自动化构建、测试、部署和其他操作。Gitea 是一个轻量化的、自托管的 Git 服务，当我们想在内网或自有服务器上构建一条完善且私有化的 CI/CD 流水线时，Gitea Actions 是一个非常不错的选择。

1.2 为什么使用 Gitea Actions？

1. 私有化和可控性：Gitea 是自托管的，所有代码、镜像都在你的服务器或者私有云环境中运行，对安全和合规有较高要求的组织会更青睐。
2. 对 GitHub Actions 熟悉度高：语法、目录结构、关键字与 GitHub Actions 极其相似，学习成本低。
3. 更轻量、更简单：相比于其他 CI/CD 工具，如 Jenkins、GitLab CI 等，Gitea + Gitea Actions 安装、配置更加轻量，对资源占用比较友好。
4. 无缝集成：使用同一个系统完成代码托管和 CI/CD 工作流，无需额外安装插件或对接第三方服务。

二、如何通过 Docker Compose 安装 Gitea 和 Gitea Action

下面我们一步步来，使用 Docker Compose 快速安装 Gitea + Gitea Actions。

2.1 准备工作

1. 服务器环境：一台安装了 Docker 和 Docker Compose 的服务器（如 Ubuntu、CentOS 等）。
2. 端口、权限：确保 80 或 3000（以及其他想要使用的端口）在防火墙或云服务商处已放行。
3. Docker、Docker Compose：确保服务器上已正确安装 Docker、Docker Compose。

2.2 Docker Compose 示例文件

下面是一个最小化配置的示例，仅供参考，可以根据需求进行拓展。这里的关键是同时配置 gitea 和 gitea runner。

注意：有一些社区维护的 community docker-compose examples 可以参考，但需要自行在 docker-compose.yml 中添加针对 Actions Runner 的配置。

version: \'3\'services: gitea: image: gitea/gitea:1.20.4 # 或者最新版本 container_name: gitea restart: always ports: - \"3000:3000\" # 访问Web界面 - \"222:22\" # SSH端口 volumes: - ./data:/data environment: - USER_UID=1000 - USER_GID=1000 - GITEA__server__DOMAIN=localhost - GITEA__server__SSH_DOMAIN=localhost - GITEA__server__HTTP_PORT=3000 - GITEA__server__ROOT_URL=http://localhost:3000 # 如果要开启邮件通知和其他功能，可以在这里添加相应配置 runner: image: gitea/act_runner:latest container_name: gitea-actions-runner restart: always depends_on: - gitea environment: - GITEA_INSTANCE_URL=http://gitea:3000 - RUNNER_NAME=runner-1 - RUNNER_CHECK_INTERVAL=30 # 下面的TOKEN需要手动填入（获取方法见下文） - GITEA_RUNNER_REGISTRATION_TOKEN=REPLACE_WITH_ACTUAL_TOKEN volumes: - /var/run/docker.sock:/var/run/docker.sock

1. gitea 服务：使用官方镜像 gitea/gitea:latest。
2. runner 服务：使用官方镜像 gitea/act_runner:latest，依赖 gitea。
3. GITEA_RUNNER_REGISTRATION_TOKEN：该环境变量是注册 Runner 的关键，需要我们在 Gitea 的管理后台获取一个有效的 Token，下面会讲解如何获取。

2.3 获取 Runner Registration Token

1. 启动 gitea 容器：docker-compose up -d。
2. 通过浏览器访问 http://:3000，进行 首次安装引导，创建管理员账号等操作。
3. 登录 Gitea 后，点击右上角头像 -> Admin Panel（管理后台） -> 在左侧菜单里找到 “Runners”。
4. 点击 “New Registration Token” 按钮生成一个新的 Token，复制下来，填入到 docker-compose.yml 中 GITEA_RUNNER_REGISTRATION_TOKEN=REPLACE_WITH_ACTUAL_TOKEN 的位置。
   

然后再次运行：

docker-compose up -d

等待容器启动后，runner 服务就会自动注册到 Gitea 中，此时在 Gitea 的 Runner 页面应该能看到一个已上线（Active）的 Runner。

三、Gitea Actions 的工作原理与常用用法

3.1 工作原理简述

1. 触发器（Events）：像 push、pull_request、tag_push 等事件会触发对应的工作流。
2. 工作流（Workflow）文件：默认存储在仓库的 .gitea/workflows/ 目录下（或自定义）。类似 GitHub Actions，一般命名为 main.yml 或 *.yml。
3. Runner：一旦事件触发，Gitea 会调用 Runner 进行执行。Runner 就是一个容器/服务器，里边通过 act 工具解析并执行 .gitea/workflows/*.yml 中的 steps。
4. steps / jobs：在定义的 workflow 中，可以分多个 job，每个 job 再包含多个 step，依次执行 shell 命令或调用各种 actions（如 actions/checkout@v4 等）。

3.2 存放工作流文件的位置

• 默认位置：在 Gitea 仓库的根目录下新建 .gitea/workflows/ 文件夹，然后在里面放置你的工作流文件，如 main.yml、build.yml 等。
• 可自定义：如果你在仓库的 Settings 里修改了默认的 workflow 路径，你就需要把 .yml 文件放在你指定的目录里。

例如，我们可以在仓库中新建：

.gitea └─ workflows └─ main.yml

然后把下面这段示例写到 main.yml 里即可。

四、动手实践：示例 Gitea Actions Workflow 详解

以下是提供的 Action 样例，将它放到 .gitea/workflows/main.yml（或你所设置的其他文件名）中即可使用。下面这段action完成了构建镜像保存本地，并将镜像时间戳版本和最新版本推到docker hub wenhao96 仓库，最后删除过程中产生的磁盘空间占用文件。

name: Gitea Actions Demorun-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀on: [push]jobs: Explore-Gitea-Actions: runs-on: ubuntu-latest steps: - run: echo \"🎉 The job was automatically triggered by a ${{ gitea.event_name }} event.\" - run: echo \"🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!\" - run: echo \"🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}.\" - name: Check out repository code uses: actions/checkout@v4 - run: echo \"💡 The ${{ gitea.repository }} repository has been cloned to the runner.\" - name: List files in the repository run: | ls ${{ gitea.workspace }} - name: Build Docker image run: | docker build -t ${{ gitea.repository }}:latest . - name: Log in to Docker Hub env: DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }} run: | echo \"${DOCKER_PASSWORD}\" | docker login -u \"${DOCKER_USERNAME}\" --password-stdin - name: Tag and push Docker image run: | TIMESTAMP=$(date +\'%Y%m%d%H%M%S\') docker tag ${{ gitea.repository }}:latest wenhao96/$(basename ${{ gitea.repository }}):${TIMESTAMP} docker push wenhao96/$(basename ${{ gitea.repository }}):${TIMESTAMP} docker tag ${{ gitea.repository }}:latest wenhao96/$(basename ${{ gitea.repository }}):latest docker push wenhao96/$(basename ${{ gitea.repository }}):latest docker rmi wenhao96/$(basename ${{ gitea.repository }}):${TIMESTAMP} docker rmi wenhao96/$(basename ${{ gitea.repository }}):latest - name: Clean up run: | docker builder prune --all --force docker volume prune -f docker network prune -f docker system df docker rmi $(docker images --filter \"dangling=true\" -q) || true - run: echo \"🍏 This job\'s status is ${{ job.status }}.\"

4.1 关键字段解读

1. name: Gitea Actions Demo：该工作流的名称。
2. run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀：在运行时显示的名称（这里通过变量将执行者名字展示出来）。
3. on: [push]：意味着当有人向该仓库 push 提交时自动触发此工作流。
4. jobs: Explore-Gitea-Actions:：定义一个名为 Explore-Gitea-Actions 的工作（Job）。
5. runs-on: ubuntu-latest：指定该 job 在何种 Runner 环境运行。
6. steps:：工作流步骤依次列出。

4.2 核心功能解读

1. actions/checkout@v4：将当前仓库代码下载到 Runner 的工作目录内。
2. docker build...：构建 Docker 镜像，使用 ${{ gitea.repository }} 作为镜像名称。
3. docker login：通过 secrets 获取 Docker Hub 用户名、密码，并执行 Docker 登录。
4. Tag and push Docker image：通过时间戳和 basename ${{ gitea.repository }} 的方式给镜像进行多标签。
5. docker rmi：在本地移除已推送的镜像，节省空间。
6. Clean up：最后一步进行 Docker 系统资源清理。

五、Secrets 的添加与常用功能

5.1 如何在 Gitea 中添加 Secrets

1. 进入你的仓库，在右上角点击 “Settings”。
2. 在左侧或顶部导航栏中查看是否有 “Secrets” 或 “Secrets and Variables” 入口（不同版本界面略有差异）。
3. 点击 “New secret”，添加 DOCKER_USERNAME、DOCKER_PASSWORD 等。
4. 在 workflow 文件中，就可以通过 ${{ secrets.DOCKER_USERNAME }} 和 ${{ secrets.DOCKER_PASSWORD }} 来调用。

5.2 常用功能与拓展

1. 缓存（Cache）：Gitea Actions 提供和 GitHub Actions 类似的缓存机制，可以加快依赖安装和构建速度。
2. 并行（parallel）和串行（serial）：支持在 workflow 文件中配置多个 job 并行执行，或者串行执行。
3. 多环境测试：可以针对不同的 Node.js 版本或 Python 版本分别执行测试，帮助确保兼容性。
4. Conditional（条件执行）：可以根据分支名、路径、标签等判断是否执行某些步骤。
5. Artifacts（构建产物）：可以将生成的日志、构建产物进行上传与存储，以方便后续查看。

六、扩展写法与更多思维发散

1. 多 Job 依赖
   你可以定义多个 jobs，比如 build-backend、build-frontend、deploy，让后续的 job 依赖前者产物：

   jobs: build-backend: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Build backend run: npm run build build-frontend: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Build frontend run: npm run build deploy: runs-on: ubuntu-latest needs: [build-backend, build-frontend] # 依赖前两个 jobs 完成后再执行 steps: - name: Deploy run: echo \"Deploying...\"

2. 基于标签或发布版本进行自动部署
   如果你想在创建 Git 标签或者发布发布版本（Release）时自动构建并推送 Docker 镜像，只需将 on: [push] 改成：

   on: push: tags: - \'v*.*.*\'

   即可在打 tag 时触发。

3. 自定义 Runner 环境
   在复杂场景下，你可能不想使用官方的 ubuntu-latest，而是使用自定义镜像或自定义服务器。可以在 Gitea Actions Runner 中指定相应标签，然后在 workflow 中写上：

   runs-on: [self-hosted, custom-runner-label]

   这样可以充分利用你自定义 Runner 的环境依赖。

4. 结合其他服务

   • 消息通知：在构建完成后，通过调用 curl 或者特定的 Action，将构建状态发送到 Slack、微信机器人、飞书等。
   • 打包发布：将构建产物 (如前端的 dist 文件) 上传到对象存储服务 (如 Minio、S3、OSS、COS 等)。
   • 多环境交付：在测试环境或生产环境中，使用同一套工作流脚本做不同操作。

5. CI/CD 最佳实践

   • 最小权限原则：只给 Runner 分配必要的访问权限和 Secrets。
   • 分支策略：使用 feature 分支进行合并请求 (Pull Request)，仅在 main/master 分支或 release 分支才进行部署或打包。
   • 可观测性：通过 Gitea 或 Runner 自带的日志功能进行调试和追踪，也可将日志发送至 ELK、Grafana Loki 等观察系统中。

七、CICD成功展示

八、结语

通过以上内容，你应该能比较全面地了解 Gitea Actions 的工作模式以及如何快速上手构建自己的 CI/CD 流水线。从基础安装到 Docker 镜像构建再到 Secrets 管理，都涉及了实际使用的常见场景。另外，通过发散思维可以拓展到更多功能，比如多环境测试、缓存和Artifacts，甚至是结合其他服务进行完整的 DevOps 流程。

你可能获得的收益：

• 与 GitHub Actions 一脉相承，学习成本低。
• 自托管可控，满足私有化需求。
• 使用方式灵活，可以根据项目类型自由定制工作流。

如果你打算把 Gitea Actions 部署到企业内部环境（内网）进行大规模使用，建议查看官方文档或社区分享，了解集群化 Runner、负载均衡、备份以及高可用部署等更深入的话题。

温馨提示：本文示例仅作演示之用，在真实生产环境中需要根据自身项目的需求与安全策略进行更细致的配置。

通过上述内容，你就已经基本理解了这个方法，基础用法我也都有展示。如果你能融会贯通，我相信你会很强

Best
Wenhao (楠博万)

网上鲜花订购