第五部分：Gitea runner + K8S 流水线构建指南

青萍叙事2025-10-14

📝 前言

在现代软件交付体系中，CI/CD（持续集成与持续部署）已成为研发效率的关键组成部分。

虽然 GitHub Actions 功能强大，但对于自建代码仓库或私有化部署需求的团队而言，Gitea Actions 提供了一个轻量、安全且兼容性极高的替代方案。

本文将介绍如何通过 Kubernetes 中运行 Gitea Runner，实现一套完整的自动化构建与部署流水线。

📌 Runner 运行在 K8S 上的优势

相较于直接在主机或虚拟机运行，将 Gitea Runner 部署到 Kubernetes 带来以下显著优势：

弹性伸缩

Runner 可根据任务负载自动扩缩容，确保在高并发构建场景下保持稳定性能，同时在空闲时释放资源，降低成本。

资源隔离与安全性

每个构建任务都在独立 Pod 中执行，不同项目间互不干扰，最大限度降低安全风险与环境污染问题。

一致性与环境可复用

借助容器化环境，Runner 的执行环境可通过镜像精确控制，避免“在我电脑上没问题”的情况，实现可预测的构建。

集群统一管理

所有 Runner 作为 K8S 工作负载运行，日志、监控、网络策略均可通过现有集群工具（如 Prometheus、Grafana）统一管理。

PS：我们之前也有介绍过通过二进制的方式部署 Runner：《使用二进制部署 Gitea Runner 指南（实战二）》

📋 前提条件

已部署 Gitea 服务端

可参看之前的文章：《使用 Docker 快速部署 Gitea 指南（实战一）》

PS：当然也可以将 Gitea 服务端也一并部署到 K8S 集群上。

已安装部署 kubernetes 集群

可参看之前的文章一键部署：《第四部分：使用 sealos 部署集群》

🚀 详细步骤

1️⃣ 创建 Runner Token

进入 Gitea 服务管理页面 → 设置 → Actions → 创建 Runner Token，复制Token。

后续注册 Runner 时使用。

2️⃣ 在 Kubernetes 中部署 Gitea Runner

gitea-runner.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitea-runner
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gitea-runner
  template:
    metadata:
      labels:
        app: gitea-runner
    spec:
      containers:
        - name: runner
          image: gitea/act_runner:latest
          args: ["daemon"]
          env:
            - name: GITEA_INSTANCE_URL
              value: "http://git.luhome.com" # 填自己的Gitea域名
            - name: GITEA_RUNNER_REGISTRATION_TOKEN
              value: xLm8BDFRf...... # 填上面复制的Token
            - name: GITEA_RUNNER_NAME
              value: "k8s-runner"
            - name: GITEA_RUNNER_LABELS
              value: "k8s:docker://docker.gitea.com/runner-images:ubuntu-latest"
            - name: DOCKER_HOST
              value: "unix:///var/run/docker.sock"
          volumeMounts:
            - name: docker-sock
              mountPath: /var/run/docker.sock # 挂载docker，也可以使用dind模式
            - name: workdir
              mountPath: /data
      volumes:
        - name: docker-sock
          hostPath:
            path: /var/run/docker.sock
        - name: workdir
          emptyDir: {}

执行部署命令：

kubectl apply -f gitea-runner.yaml

# 验证 Runner 状态
kubectl get pods

若显示为 Running，并且在 Gitea → Actions → Runner 页面中状态为 **空闲**，表示成功注册。

3️⃣ 实战示例：构建并部署镜像

.gitea/workflows/build.yaml 示例：

name: Build and Deploy

on:
  push:
    branches:
      - main

# 引用 kubeconfig，需要提前在 gitea 中创建secrets
env:
  KUBECONFIG: ${{ secrets.KUBECONFIG }}

jobs:
  build:
    # 注意标签需要填k8s了
    runs-on: k8s
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build Docker image
        run: |
          docker build -t myapp:latest .

      - name: Push image to registry
        run: |
          docker tag myapp:latest registry.example.com/myapp:latest
          docker push registry.example.com/myapp:latest

      - uses: azure/setup-kubectl@v4
        with:
          version: 'v1.30.0'
      
      - name: Write kubeconfig
        run: |
          echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config

      - name: Deploy to K8S
        run: |
          kubectl set image deployment/myapp myapp=registry.example.com/myapp:latest