配置 GitHub Pages 站点的发布源

可将 GitHub Pages 站点配置为在将更改推送到特定分支时发布，也可以编写 GitHub Actions 工作流来发布站点。

谁可以使用此功能？

People with admin or maintainer permissions for a repository can configure a publishing source for a GitHub Pages site.

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 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 工作流来发布站点。

如果不需要对站点的生成过程进行任何控制，则建议在将更改推送到特定分支时发布站点。 可以指定要用作发布源的分支和文件夹。 源分支可以是存储库中的任何分支，源文件夹可以是源分支上的存储库根目录 (/)，也可以是源分支上的 /docs 文件夹。 将更改推送到源分支时，源文件夹中的更改将发布到 GitHub Pages 站点。

如果想使用 Jekyll 以外的生成过程，或者不想使用专用分支来保存已编译的静态文件，则建议编写 GitHub Actions 工作流来发布站点。 GitHub Enterprise Cloud 为常见的发布应用场景提供工作流模板，以帮助编写工作流。

警告：除非你的企业使用 Enterprise Managed Users，否则默认情况下 GitHub Pages 站点可以在 Internet 上公开，即使该站点的存储库是私有的或内部的。 可以通过管理站点的访问控制来私下发布站点。 否则，如果站点的存储库中有敏感数据，你可能想要在发布前删除数据。 有关详细信息，请参阅“关于仓库”和“更改 GitHub Pages 站点的可见性”。

从分支进行发布

  1. 确保你要用作发布源的分支已经存在于你的存储库中。

  2. 在 GitHub Enterprise Cloud 上，导航到站点的仓库。

  3. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  4. 在边栏的“代码和自动化”部分中，单击“ Pages”。

  5. 在“生成和部署”的“源”下，选择“从分支进行部署”。

  6. 在“生成和部署”下，使用分支下拉菜单并选择发布源。

    GitHub 存储库中 Pages 设置的屏幕截图。 用于为发布源选择分支的菜单（标有“无”）用深橙色框出。

  7. （可选）使用文件夹下拉菜单选择发布源的文件夹。

    GitHub 存储库中 Pages 设置的屏幕截图。 用于为发布源选择文件夹的菜单（标有“/(根)”）用深橙色框出。

  8. 单击“ 保存”。

从分支进行发布疑难解答

Note

If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "GitHub Actions 文档."

Note

  • 如果从分支进行发布且站点尚未自动发布，请确保具有管理员权限和经验证的电子邮件地址的人员已将站点推送到发布源。
  • 由使用 GITHUB_TOKEN 的 GitHub Actions 工作流推送的提交不会触发 GitHub Pages 生成。

如果选择任意分支上的 docs 文件夹作为发布源，稍后从存储库中的该分支中删除 /docs 文件夹，则站点不会生成，并且你将收到缺失 /docs 文件夹的页面生成错误消息。 有关详细信息，请参阅“排查 GitHub Pages 站点的 Jekyll 构建错误”。

GitHub Pages 站点将始终使用 GitHub Actions 工作流程运行进行部署，即使您已将 GitHub Pages 站点配置为使用其他 CI 工具构建也是如此。 大多数外部 CI 工作流通过将生成输出提交到存储库的 gh-pages 分支来“部署”到 GitHub Pages，且通常包含 .nojekyll 文件。 发生这种情况时， GitHub Actions 工作流程将检测分支不需要构建步骤的状态，并且仅执行将站点部署到 GitHub Pages 服务器所需的步骤。

若要查找构建或部署的潜在错误，可以通过查看仓库的工作流程运行来检查 GitHub Pages 站点的工作流程运行情况。 有关详细信息，请参阅“查看工作流程运行历史记录”。 有关如何在出现错误时重新运行工作流的详细信息，请参阅“重新运行工作流程和作业”。

使用自定义 GitHub Actions 工作流进行发布

若要将站点配置为使用 GitHub Actions 进行发布，请执行以下操作：

  1. 在 GitHub Enterprise Cloud 上，导航到站点的仓库。

  2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“代码和自动化”部分中，单击“ Pages”。

  4. 在“生成和部署”的“源”下，选择“GitHub Actions”。

  5. GitHub Enterprise Cloud 将建议多个工作流模板。 如果已有用于发布站点的工作流，可跳过此步骤。 否则，请选择其中一个选项来创建 GitHub Actions 工作流。 有关创建自定义工作流的详细信息，请参阅“创建自定义 GitHub Actions 工作流以发布站点”。

    GitHub Pages 不会将特定工作流与 GitHub Pages 设置相关联。 但 GitHub Pages 设置将链接到最近部署你的站点的工作流运行。

创建自定义 GitHub Actions 工作流以发布站点

有关 GitHub Actions 的详细信息，请参阅“GitHub Actions 文档”。

将站点配置为使用 GitHub Actions 进行发布时，GitHub Enterprise Cloud 将针对常见发布应用场景建议工作流模板。 工作流的一般流程如下：

  1. 每当推送到存储库的默认分支，或者每当从“操作”选项卡手动运行工作流时，就会触发工作流。
  2. 使用 actions/checkout 操作签出存储库内容。
  3. 如果站点需要，请生成任何静态站点文件。
  4. 使用 actions/upload-pages-artifact 操作将静态文件作为项目上传。
  5. 如果推送到默认分支触发了工作流，请使用 actions/deploy-pages 操作来部署项目。 如果拉取请求触发了工作流，则跳过此步骤。

工作流模板使用名为 github-pages 的部署环境。 如果存储库尚未包含名为 github-pages 的环境，则自动创建该环境。 建议添加部署保护规则，确保仅默认分支可部署到该环境。 有关详细信息，请参阅“管理部署环境”。

注意：存储库文件中的 CNAME 文件不会自动添加或删除自定义域。 必须通过存储库设置或 API 配置自定义域。 有关详细信息，请参阅“管理 GitHub Pages 站点的自定义域”和“GitHub Pages 的 REST API 终结点”。

使用自定义 GitHub Actions 工作流进行发布故障排除

有关如何对 GitHub Actions 工作流进行故障排除的信息，请参阅“监控和故障排除工作流程”。