Forgejo Pages CI 范例（page-test）

一个最小、可直接复制的 Forgejo Pages 发布范例：静态站点 + Forgejo Actions 自动构建 + 官方 Pages Action 上传。

• 仓库：https://git.gjz010.com/gjz010.dev/page-test （私有）
• 默认分支：main
• 运行器：Docker runner，标签 ubuntu-latest

发布结果以仓库 Actions 运行记录为准。

目录结构

.forgejo/workflows/publish.yaml   # 发布工作流
scripts/build.sh                  # 构建脚本：把 site/ 复制到 dist/
site/index.html
site/style.css

站点没有构建依赖，build.sh 只复制静态文件。

本地构建

sh scripts/build.sh

产物在 dist/，这就是上传目录。

发布工作流

.forgejo/workflows/publish.yaml 在 push 到 main 与手动 workflow_dispatch 时触发。关键步骤：

- uses: https://git.gjz010.com/actions/checkout@releases/v6
- run: sh scripts/build.sh
- uses: https://codeberg.org/git-pages/action@v2
  with:
    site: https://pages.gjz010.com/deploy/gjz010.dev/page-test/
    token: ${{ forgejo.token }}
    source: dist

• checkout 使用绝对地址，避免自建实例无法解析相对 action。
• site 是上传入口，不是阅读地址。
• source: dist 表示上传本地目录。
• path 是 URL 子路径，本例不设置。
• token 用 Forgejo 自带的 CI token ${{ forgejo.token }}，不需要手工配置 PAT secret。

复制到你自己的仓库

1. 把 scripts/、site/、.forgejo/ 复制到你的仓库。
2. 把 site: 改成你自己 owner/repo 的上传入口，例如 https://pages.gjz010.com/deploy/<owner>/<repo>/。
3. 确认仓库已启用 Forgejo Actions，并有一个标签为 ubuntu-latest 的 Docker runner，且能拉取 Action 镜像。
4. 让平台先分配/绑定阅读域名，然后 push 到 main 触发发布。

阅读域名由平台提供；绑定后多个域名平等读取同一 repoID 的站点，CI 上传不需要 manager 登录。本例阅读域名：

• https://pages-lab.gjz010.page/
• https://pages-test.gjz010.com/ （需完成 Cloudflare 域名与证书验证）

注意

私有仓库的发布产物是公开的，不要把机密放进 site/。

排查

• 先看 Actions 运行日志，定位 build 或 action 步骤的报错。
• 401：token 权限或平台侧授权问题。
• 404：域名未绑定，或站点尚未发布。
• 域名解析/证书未生效：可能仍在 Cloudflare 待激活。