使用自定义工作流与 GitHub Pages

您可以通过创建工作流文件或从预定义的工作流中选择来利用 GitHub Actions 和 GitHub Pages 的优势。

谁可以使用此功能？

GitHub Pages 可用于具有 GitHub Free 和 GitHub Free for organizations 的公共仓库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。有关更多信息，请参阅“GitHub 的套餐”。

GitHub Pages 现在使用 GitHub Actions 执行 Jekyll 构建。当使用分支作为构建源时，如果您想使用内置的 Jekyll 工作流，则必须在您的仓库中启用 GitHub Actions。或者，如果 GitHub Actions 不可用或已禁用，则将.nojekyll文件添加到源分支的根目录将绕过 Jekyll 构建过程并直接部署内容。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

本文内容

关于自定义工作流

自定义工作流允许通过使用 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@v3

此操作有助于支持从任何静态站点生成器到 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@v1

部署 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@v1
# ...

链接单独的构建和部署作业

您可以在单个工作流文件中链接您的build和deploy作业，从而无需创建两个单独的文件即可获得相同的结果。要在工作流文件中开始操作，您可以在jobs下定义一个build和deploy作业来执行您的作业。

# ...

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

  # 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@v2
# ...

在某些情况下，您可能选择将所有内容组合到一个作业中，尤其是在不需要构建过程的情况下。因此，您将只关注部署步骤。

# ...

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@v4
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

# ...

您可以定义您的作业以在不同的运行器上顺序或并行运行。有关更多信息，请参阅“选择工作流的功能”。