关于发布源
可以在将更改推送到特定分支时发布站点,也可以编写 GitHub Actions 工作流来发布站点。
如果不需要对站点的生成过程进行任何控制,则建议在将更改推送到特定分支时发布站点。 可以指定要用作发布源的分支和文件夹。 源分支可以是存储库中的任何分支,源文件夹可以是源分支上的存储库根目录 (/
),也可以是源分支上的 /docs
文件夹。 将更改推送到源分支时,源文件夹中的更改将发布到 GitHub Pages 站点。
如果想使用 Jekyll 以外的生成过程,或者不想使用专用分支来保存已编译的静态文件,则建议编写 GitHub Actions 工作流来发布站点。 GitHub 为常见的发布应用场景提供工作流模板,以帮助编写工作流。
Warning
GitHub Pages 站点可以在 Internet 上公开,即使该网站的存储库是专用的(如果计划或组织允许)。 如果站点的存储库中有敏感数据,你可能想要在发布前删除数据。 有关详细信息,请参阅“关于仓库”。
从分支进行发布
-
确保你要用作发布源的分支已经存在于你的存储库中。
-
在 GitHub 上,导航到站点的仓库。
-
在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。
-
在边栏的“代码和自动化”部分中,单击“ Pages”。
-
在“生成和部署”的“源”下,选择“从分支进行部署”。
-
在“生成和部署”下,使用分支下拉菜单并选择发布源。
-
(可选)使用文件夹下拉菜单选择发布源的文件夹。
-
单击“ 保存”。
从分支进行发布疑难解答
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 进行发布,请执行以下操作:
-
在 GitHub 上,导航到站点的仓库。
-
在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。
-
在边栏的“代码和自动化”部分中,单击“ Pages”。
-
在“生成和部署”的“源”下,选择“GitHub Actions”。
-
GitHub 将建议多个工作流模板。 如果已有用于发布站点的工作流,可跳过此步骤。 否则,请选择其中一个选项来创建 GitHub Actions 工作流。 有关创建自定义工作流的详细信息,请参阅“创建自定义 GitHub Actions 工作流以发布站点”。
GitHub Pages 不会将特定工作流与 GitHub Pages 设置相关联。 但 GitHub Pages 设置将链接到最近部署你的站点的工作流运行。
创建自定义 GitHub Actions 工作流以发布站点
有关 GitHub Actions 的详细信息,请参阅“GitHub Actions 文档”。
将站点配置为使用 GitHub Actions 进行发布时,GitHub 将针对常见发布应用场景建议工作流模板。 工作流的一般流程如下:
- 每当推送到存储库的默认分支,或者每当从“操作”选项卡手动运行工作流时,就会触发工作流。
- 使用
actions/checkout
操作签出存储库内容。 - 如果站点需要,请生成任何静态站点文件。
- 使用
actions/upload-pages-artifact
操作将静态文件作为项目上传。 - 如果推送到默认分支触发了工作流,请使用
actions/deploy-pages
操作来部署项目。 如果拉取请求触发了工作流,则跳过此步骤。
工作流模板使用名为 github-pages
的部署环境。 如果存储库尚未包含名为 github-pages
的环境,则自动创建该环境。 建议添加部署保护规则,确保仅默认分支可部署到该环境。 有关详细信息,请参阅“管理部署环境”。
Note
存储库文件中的 CNAME
文件不会自动添加或删除自定义域。 必须通过存储库设置或 API 配置自定义域。 有关详细信息,请参阅“管理 GitHub Pages 站点的自定义域”和“GitHub Pages 的 REST API 终结点”。
使用自定义 GitHub Actions 工作流进行发布故障排除
有关如何对 GitHub Actions 工作流进行故障排除的信息,请参阅“监控和故障排除工作流程”。