使用自定义工作流与 GitHub Pages

关于自定义工作流

自定义工作流允许通过 GitHub Actions 构建 GitHub Pages 站点。您仍然可以通过工作流文件选择要使用的分支，但使用自定义工作流可以实现更多功能。要开始使用自定义工作流，必须先为当前仓库启用它们。更多信息，请参阅 为您的 GitHub Pages 站点配置发布来源。

配置 configure-pages 操作

GitHub Actions 通过 configure-pages 操作实现对 GitHub Pages 的使用，并允许您收集网站的各种元数据。更多信息，请参阅 configure-pages 操作。

要使用此操作，请将以下代码段放在所需工作流的 jobs 下。

- name: Configure GitHub Pages
  uses: actions/configure-pages@v5

此操作帮助支持将任何静态站点生成器的产出部署到 GitHub Pages。为减少重复工作，您可以针对常用的静态站点生成器使用工作流模板。更多信息，请参阅 使用工作流模板。

配置 upload-pages-artifact 操作

upload-pages-artifact 操作使您能够打包并上传构件。GitHub Pages 的构件应为包含单个 tar 文件的压缩 gzip 存档。该 tar 文件大小必须小于 10GB，并且不得包含任何符号链接或硬链接。更多信息，请参阅 upload-pages-artifact 操作。

要在当前工作流中使用此操作，请将以下代码段放在 jobs 下。

- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v4

部署 GitHub Pages 构件

deploy-pages 操作负责部署构件所需的相关设置。为确保正常运行，需要满足以下要求：

• 作业必须至少拥有 pages: write 和 id-token: write 权限。
• needs 参数必须设置为构建步骤的 id。若未设置此参数，可能导致独立的部署不断寻找尚未创建的构件。
• 必须建立 environment 以强制执行分支/部署保护规则。默认环境为 github-pages。
• 若要将页面的 URL 作为输出，请使用 url: 字段。

更多信息，请参阅 deploy-pages 操作。

# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...

关联独立的构建和部署作业

您可以在同一个工作流文件中关联 build 和 deploy 作业，从而无需创建两个独立的文件即可实现相同效果。要开始编写工作流文件，只需在 jobs 下定义 build 和 deploy 作业即可执行。

# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
# ...

在某些情况下，您可能会选择将所有步骤合并为一个作业，尤其是当无需构建过程时。这样就只需关注部署步骤。

# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v4
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...

您可以将作业定义为在不同的 runner 上运行，或顺序、并行执行。更多信息，请参阅 选择工作流的执行方式。