Gitea Action 定时构建和手动构建指南（实战五）

📝 前言

这是 DevOps 专题的第七篇，回顾一下前几篇的内容：

这一篇我们继续介绍如何使用 Gitea Actions 来完成定时构建和手动构建。

🧭 背景介绍

在使用 Gitea 搭建自托管 Git 平台的过程中，很多开发者希望结合 CI/CD 实现自动化构建。

Gitea Actions（兼容 GitHub Actions Workflow）现已支持多种触发机制，包括定时触发和手动触发，极大地增强了 Gitea 在持续集成场景中的实用性。

🔍 使用场景

  • 每天定时拉取远程数据并构建静态站点（如：本站的朋友动态）
  • 手动触发构建以测试代码变更
  • 每周定期运行清理脚本或备份任务

📋 前提条件

在开始之前，请确保你已满足以下条件：

🚀 详细步骤

1️⃣ 定时构建配置

创建 .gitea/workflows/build.yaml 文件，内容参考如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
name: Scheduled Build

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点 (UTC 时间)

jobs:
  build:
    runs-on: host
    steps:
      - name: 检出代码
        uses: actions/checkout@v3

      - name: 执行构建任务
        run: |
          echo "开始构建..."
          # 执行构建命令

配置说明：

  • on.schedule：这里我们在on标签下，新增了schedule，并配置了cron表达式，需要注意的是时间默认是按照UTC来的，如果想要按照北京时间执行，需要将北京时间-8小时，因为北京时间是属于东八区，是在UTC基础上+8小时。

例如：我们示例里面写的是凌晨2点，实际执行时间就是在北京时间上午10点。

如果想要在实际的北京时间凌晨2点执行，那边我们这里应该配置的是：0 18 * * *。

另外 Gitea Action 也支持配置多个定时任务，只需要再加一条cron表达式即可，如：

1
2
3
4
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点 (UTC 时间)
    - cron: '0 3 * * *'  # 每天凌晨3点 (UTC 时间)

最后再贴一下cron表达式对应的时间配置：

1
2
3
4
5
6
7
8
┌───────────── 分钟 (0 - 59)
│ ┌───────────── 小时 (0 - 23)
│ │ ┌───────────── 日 (1 - 31)
│ │ │ ┌───────────── 月 (1 - 12)
│ │ │ │ ┌───────────── 星期 (0 - 6，0=周日)
│ │ │ │ │
│ │ │ │ │
* * * * *

PS：提醒一下定时任务配置仅在仓库的默认分支(一般是main，除非手动修改)生效。

当达到定时任务时，我们在项目的Actions中可查看到已计划的执行，表明定时执行成功了：

有可能会延迟个1-2分钟都是正常的。

2️⃣ 手动构建配置（控制台）

手动构建有两种方式，一种是在 Gitea 控制台点击构建，还有一种是通过接口的形式触发构建。

我们先介绍通过控制台的方式进行手动构建，只需要在上面的yaml文件里面添加一行配置即可，参考如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
name: Scheduled Build

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点 (UTC 时间)
  # 手动构建
  workflow_dispatch:

jobs:
  build:
    runs-on: host
    steps:
      - name: 检出代码
        uses: actions/checkout@v3

      - name: 执行构建任务
        run: |
          echo "开始构建..."
          # 执行构建命令

当我们在on标签下面添加workflow_dispatch:后，进入 Gitea 项目控制台 → Actions → 工作流文件，就可以看到新出现的**运行工作流**按钮了，点击即可触发手动构建，如下图：

3️⃣ 手动构建配置（接口触发）

除了在 Web 界面点击**运行工作流**按钮外，Gitea 也支持通过 API 方式手动触发 workflow_dispatch 类型的构建，适用于 CLI 脚本、Webhook 联动、自动化平台（如 Jenkins、n8n）等场景。

相比在控制台手动点击构建，通过接口的方式触发无疑是要更加灵活。

PS：我的博客站点就是通过在Notion中点击按钮触发接口执行的构建，不用再到Gitea上去找项目点执行了。

首先我们获取个人 Token，进入 Gitea 个人设置 → 应用 → 生成新的令牌。

因为是内网环境，权限直接全部勾选，随便填一个令牌名称，点击生成令牌即可：

生成完的令牌我们需要保存好，在下面调用接口的时候会用到。

接口请求URL：

1
POST {Gitea实例地址}/api/v1/repos/{用户名}/{仓库名}/actions/workflows/{工作流文件}/dispatches

请求头：

1
2
Authorization: token <你的令牌>
Content-Type: application/json

请求体：

1
2
3
{
    "ref": "refs/heads/{分支名}"
}

cURL 命令参考如下：

1
2
3
4
5
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  http://your.gitea.domain/api/v1/repos/{用户名}/{仓库名}/actions/workflows/build.yaml/dispatches \
  -d '{"ref": "refs/heads/{分支名}"}'

请求成功后返回 204 No Content，不会有输出，可以到Gitea控制台 → Actions里面查看是否有构建。

✅ 总结

最后总结一下通过本指南，我们系统地了解了如何在 Gitea 中：

  • 配置定时构建（schedule）
  • 支持多个 cron 表达式（UTC 时间换算）
  • 启用手动触发构建（workflow_dispatch）
  • 通过 Gitea API 实现自动化触发构建流程

Gitea Actions 提供了灵活而强大的触发机制，使得在自托管环境中实现类似 GitHub Actions 的自动化流程成为可能。

无论是定期同步、备份、构建部署，还是集成其他工具的自动触发，Gitea 都能胜任。