💡 如果你的 Jekyll 博客还在用 ACCESS_TOKEN 把 _site 推到另一个分支，迁移到官方 Pages Actions 通常只需要调整一次发布模型，之后维护成本会更低。

先说结论：发布不需要个人令牌

旧教程常见的流程是：Runner 构建 _site，再用一个个人访问令牌（PAT）把静态文件推送到 gh-pages 或 built 分支。它能工作，但发布权限和个人账号绑定，令牌过期、泄露或权限过大都会变成额外风险。

GitHub 官方的 Pages Actions 流程分成两段：构建作业生成 Pages artifact，部署作业使用 GitHub 的部署令牌发布这个 artifact。工作流只声明本次任务需要的权限：

permissions:
  contents: read
  pages: write
  id-token: write

这里的 id-token: write 不是给脚本一个长期密钥，而是允许部署动作申请短期的 OIDC 身份。权限仍然应该按仓库设置和环境保护规则控制，不能把它理解成“完全不需要权限”。

旧流程的问题在哪里

下面是很多旧博客仍在使用的结构，示意中的令牌名称不是让你去创建新令牌：

- name: Deploy
  uses: JamesIves/github-pages-deploy-action@3.6.2
  with:
    ACCESS_TOKEN: $
    BRANCH: built
    FOLDER: _site

这个方案的成本主要有四个：

1. PAT 往往拥有超出 Pages 发布所需的仓库写权限。
2. 发布结果依赖一个额外分支，源码和产物容易出现分叉。
3. 第三方动作版本和令牌都需要单独维护。
4. 分支推送触发器、构建和部署混在一起，失败时不容易判断是构建问题还是发布问题。

这并不意味着所有旧动作都不安全，真正的问题是权限边界和生命周期管理。若项目有特殊的跨仓库发布需求，旧模型仍可能有用；普通的 GitHub Pages 仓库则没有必要保留这层复杂度。

迁移前先确认三件事

1. 确认默认分支

下面的示例使用 master，因为不少老仓库仍然以它作为默认分支。如果你的默认分支是 main，只改这一处：

on:
  push:
    branches: [master]

分支名必须和仓库实际设置一致，否则工作流文件虽然存在，推送文章时却不会触发。

2. 确认 Pages 的发布源

打开仓库的 Settings → Pages，将 Build and deployment → Source 设置为 GitHub Actions。如果仍然选择“从某个分支部署”，官方部署作业不会接管发布。

3. 确认 Jekyll 能在干净环境构建

仓库应有 Gemfile，并且在本地执行下面的命令能够生成 _site：

bundle install
bundle exec jekyll build

本地能构建不代表线上一定能构建。Ruby 版本、依赖锁文件和环境变量仍需在工作流中明确写出，避免“我的电脑可以”式发布。

一份可直接使用的官方流程

创建 .github/workflows/pages.yml，内容如下：

name: Deploy Jekyll site to Pages

on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true

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

      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "$"
        env:
          JEKYLL_ENV: production

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: $
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

这份配置对应 GitHub 官方 starter workflow 的结构。configure-pages 会提供 Pages 的基础路径，jekyll build 将它传给 --baseurl，因此项目站点和用户站点都能使用同一套写法。upload-pages-artifact 默认上传 _site，不需要再把构建产物提交到仓库分支。

为什么要拆成两个 job

build 只负责把源码变成静态文件，失败时不会触发部署；deploy 只消费已经生成的 artifact。这样的边界有两个好处：构建日志更容易定位，部署权限也只出现在真正需要的作业上下文里。

concurrency 则避免连续推送时排队发布一串过时版本。这里特意保留 cancel-in-progress: false，让已经开始的生产部署完成；新的提交会在合适时机继续发布。

依赖和动作版本怎么管

示例中的 @v4、@v5 是官方文档可读性更好的写法。对安全要求更高的仓库，可以将动作固定到完整 commit SHA，并在同一行保留版本注释：

uses: actions/checkout@<完整 commit SHA> # v4

固定 SHA 能防止同一个标签后来被移动，但会增加升级工作量。无论选择标签还是 SHA，都建议启用 Dependabot 的 GitHub Actions 更新，让版本升级进入 Pull Request，而不是长期手工检查。

Ruby 依赖也应该提交 Gemfile.lock（如果项目的发布环境允许），并使用 bundler-cache: true。缓存来自 lockfile 的依赖集合；lockfile 变化时，缓存键也会随之变化。不要为了“加快构建”把 _site 或包含站点内容的目录作为跨运行缓存。

迁移步骤和回滚边界

建议按下面顺序操作：

1. 新增 pages.yml，先不要删除旧工作流文件。
2. 推送到默认分支，确认 build 和 deploy 两个 job 都成功。
3. 在 Settings → Pages 确认发布源为 GitHub Actions，并访问自定义域名检查首页、文章、CSS、RSS 和 sitemap。
4. 连续推送一个只改文档的提交，确认不会重复发布旧产物。
5. 观察一次完整成功运行后，再删除旧工作流和不再使用的 PAT secret。

删除 secret 是不可逆的配置变化，应该放在新流程确认成功之后。回滚也很简单：恢复旧工作流文件并把 Pages 发布源切回原来的分支，但这会重新引入旧令牌模型，不建议把回滚状态当作长期方案。

常见失败与判断方法

页面显示旧内容

先看 Actions 中最新一次 deploy 的 environment URL，再看提交 SHA 是否与预期一致。只看到工作流“成功”还不够，必须确认 Pages 的发布源和发布提交也已经切换。

CSS 或图片 404

通常是 baseurl 没有传入，或者文章中的绝对路径以 /assets 开头却没有考虑项目站点子路径。优先使用 relative_url、absolute_url 等 Jekyll 过滤器，并检查 configure-pages 输出的 base_path。

bundle exec jekyll build 失败

先比较本地和 Runner 的 Ruby 版本，再检查 Gemfile.lock 是否提交。若错误来自未来日期文章，确认是否需要显式传入 --future，不要为了让构建通过而随意改文章日期。

Resource not accessible by integration

检查工作流顶层 permissions，以及仓库 Settings → Actions → General → Workflow permissions。Pages 部署至少需要 pages: write 和 id-token: write；构建源码通常只需要 contents: read。

发布前的最小检查清单

• 默认分支名称与 on.push.branches 一致。
• Pages Source 已切换到 GitHub Actions。
• Gemfile 和必要的 lockfile 已提交。
• 文章 Front Matter 含 title、description、keywords、author。
• 本地 bundle exec jekyll build 成功。
• Actions 的 build、artifact、deploy 三段均成功。
• 首页、文章、CSS、图片、RSS 和 sitemap 均可访问。
• 确认新流程稳定后，再删除旧 PAT 和旧发布分支。

总结

迁移的核心不是把一个第三方动作换成另一个动作，而是把“令牌推送分支”改成“权限受限的 artifact 部署”。对标准 Jekyll 博客来说，官方 Pages Actions 已经覆盖构建、上传、部署和环境地址；真正需要我们维护的是 Ruby 依赖、动作版本、权限范围和发布后的验证。

参考资料

• Setting up a GitHub Pages site with Jekyll
• Using custom workflows with GitHub Pages
• GitHub Actions starter workflow: Jekyll
• Security hardening for GitHub Actions

作者：牛马便利店一号店员