利用Gitea Actions实现MKDocs更新自动构建与发布

在使用 MkDocs 构建文档的过程中，传统的部署方式通常包括本地生成 HTML 静态文件，并手动将其移动至网站服务器的指定目录下。这种方式虽然简单直观，但在多人协作或频繁更新的项目中效率较低，容易出错。

Gitea是一款可自部署的代码托管平台，我们可以借助 Gitea Actions 实现文档的自动化部署。通过配置工作流，当文档仓库有新的提交时，Gitea Actions 将自动构建 MkDocs 项目并将生成的静态文件部署到网站服务器，大大简化了流程，提高了部署的可靠性与效率。

本文将介绍如何配置 Gitea Actions，实现 MkDocs 文档的自动构建与发布，让你的文档随代码同步更新，无需手动干预。

✅ 启用Gitea Actions

在 Gitea 1.19.0 及以上的版本支持 Gitea Actions。需要在配置文件增加以下内容来启用：

[actions]
ENABLED = true

然后确保在您的仓库中已经“启用Actions”。（位于“仓库-设置-仓库”）

🛠️ 配置 Gitea Actions

在.gitea/workflows/deploy.yml创建一个工作流文件：

name: Build and Deploy MkDocs

on:
  push:
    branches:
      - main # 更换为您需要的分支名称
    # 如果仅在部分目录修改时执行，取消注释以下内容
    #paths:
    #  - 'docs/**'
    #  - ''

jobs:
  build:
    runs-on: ubuntu-latest
    steps:

      - name: Checkout code
        uses: RouxAntoine/checkout@v3.5.4 # 这是支持子目录的fork，亦可使用actions/checkout@v4
        with:
          server-url: https://example.com/gitea # 修改为您的服务器地址

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material # 根据本地安装的包来修改

      - name: Build MkDocs site
        run: mkdocs build
        working-directory: ${{ github.workspace }}

      - name: Deploy to local directory
        run: |
          rm -rf /var/www/html/doc/* # 修改为您的网页服务器目录
          cp -r site/* /var/www/html/doc/
        env:
          RSYNC_PASSWORD: ${{ secrets.RSYNC_PASSWORD }}

✅ 部署并注册 Act Runner

首先，下载Act Runner，并移动到/bin。

chmod +x act_runner-
mv act_runner- /usr/local/bin/act_runner

其次，前往“仓库-设置-Actions-Runners”中点击“创建Runners”，复制显示的“注册令牌”。

然后，使用以下命令注册Runner：

act_runner register

按提示输入信息，但需注意在“Enter the runner labels, leave blank to use the default labels”时，使用默认值是在docker中运行。若希望在主机直接运行，请使用如ubuntu-latest:host。关于标签的更多说明请见文档。

注册完毕后在当前目录下出现.runner文件，此为Act Runner的配置文件。

最后，启动Runner。建议使用网站服务器相同用户启动，以避免移动时可能产生的权限问题。

sudo -u www-data act_runner daemon

运行后您应该能在“仓库-设置-Actions-Runners”中看到：

结果：尝试向仓库提交内容，Act Runner开始运行，MKDocs自动被移动至网站目录。

参考资料：

• 快速入门 | Gitea Documentation