GitHub Pages 手动部署：不 push 代码也能触发更新

事情是这样的。我的博客用的是 GitHub Pages，平时写文章推送到 main 分支，Actions 自动构建部署。但有时候只是想改个 typo、调个样式、或者重新触发一次部署 —— 又不想为了这点小事攒一个 commit。

传统 GitHub Pages 的 branch 模式没这选项，只能靠 push。但其实 GitHub 早就支持了自定义 Actions 工作流，配合 workflow_dispatch 就能手动点按钮触发部署。

两种 Pages 部署模式

GitHub Pages 提供两种发布源：

模式触发方式灵活性
Branch（传统）push 到指定分支自动触发低，改什么都得 commit
GitHub Actions（自定义）工作流定义触发条件高，支持 workflow_dispatch 手动触发

要手动控制部署，得先切到 Actions 模式。

切换到 Actions 模式

进仓库 Settings → Pages → Build and deployment，Source 选 GitHub Actions。

[图：GitHub Pages 设置页面，Source 下拉选 GitHub Actions]

切完之后，传统的 branch 自动部署就停了。接下来你得自己写一个部署工作流。

写部署工作流

在仓库根目录建 .github/workflows/deploy-pages.yml：

name: Deploy GitHub Pages


on:
  # 手动触发——这就是"手动部署按钮"
  workflow_dispatch:
    inputs:
      reason:
        description: '部署原因（可选）'
        required: false
        default: '手动触发'
  # 保留 push 触发也可以，二者不冲突
  push:
    branches: [main]


jobs:
27 collapsed lines
  deploy:
    # 这三个权限是 deploy-pages 必需的
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - name: Setup Pages
        uses: actions/configure-pages@v5


      # 如果你的站点需要构建（如 Hugo/Next.js/Astro），在这一步构建
      # 纯静态 HTML 可以跳过，直接上传整个目录


      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: '.'  # 要部署的目录，根据实际情况改


      - name: Deploy to GitHub Pages
        id: deploy
        uses: actions/deploy-pages@v4

push 到 main 分支后，打开仓库的 Actions 标签页，就能看到工作流名称旁边有个 “Run workflow” 按钮。

[图：Actions 页面，“Run workflow” 按钮]

三种触发方式

1. Web UI（最直观）

打开 Actions 标签页 → 点工作流名 → 点 Run workflow → 选分支 → 点绿色的 Run workflow 按钮。

手机上也能操作，App 里进 Actions 同样有这个按钮。

2. GitHub CLI（命令行）

Terminal window
# 触发部署
gh workflow run deploy-pages.yml


# 如果要指定分支
gh workflow run deploy-pages.yml --ref main


# 带参数
gh workflow run deploy-pages.yml -f reason='修复首页样式'

适合脚本化或者不想开浏览器的时候。

3. REST API（远程调用 / Webhook）

Terminal window
curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy-pages.yml/dispatches \
  -d '{"ref":"main"}'

这个适合从外部系统触发 —— 比如 CMS 发布内容后自动部署、定时任务、或者其他 CI 流水线的最后一步。

repository_dispatch：外部 webhook 触发

如果你的触发源不在 GitHub 生态内（比如自建 CMS、Pipedream、Zapier），还可以用 repository_dispatch：

on:
  repository_dispatch:
    types: [deploy-pages]

然后外部发一个 POST：

Terminal window
curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"deploy-pages"}'

这样任何能发 HTTP 请求的系统都能触发部署。

踩坑备忘

  • workflow 文件必须在默认分支上，放其他分支不会出现 Run workflow 按钮。
  • 切到 Actions 模式后，传统的 branch 自动部署会停。如果还想保留 push 自动部署，在 on 里同时加 push 和 workflow_dispatch。
  • 手机端 GitHub App 的 Run workflow 按钮不弹输入框，有 inputs 参数会直接用默认值。
  • deploy-pages 需要 id-token: write 权限，漏了会报权限错误。

总结

其实 GitHub 这一套做得挺完整的 ——workflow_dispatch 覆盖手动触发，gh workflow run 覆盖命令行，REST API 覆盖远程调用。切到 Actions 模式之后，Pages 部署的灵活性比传统 branch 模式高了一大截，而且完全不依赖第三方工具。

不管你是想” 改个 typo 不攒 commit”，还是” 从外部系统发 webhook 触发部署”，都能搞定。