GitLab Pages流水线成功但未部署问题求助

问题背景 #

使用Sphinx生成HTML，通过.gitlab-ci.yml部署到GitLab Pages，本地Runner流水线运行无异常，产物HTML本地可正常打开，但仓库侧边栏未显示Pages选项，也无法看到部署链接。

排查与解决步骤 #

• 检查Pages功能是否启用
  进入项目的「设置」→「Pages」页面，确认Pages功能已开启。部分项目默认未启用该功能，需手动开启后才能显示侧边栏入口。

• 验证artifacts路径与文件结构
  确保sphinx-build生成的HTML文件全部存放在项目根目录的public文件夹下，且根目录存在index.html。可在流水线脚本中添加以下命令验证：

  ls -la public
  

  若文件结构不符合要求，需调整sphinx-build的输出路径参数。

• 修复文件权限问题
  本地PowerShell Runner可能存在文件权限不足的情况，导致GitLab无法正确识别artifacts。在脚本中添加权限修复命令：

  chmod -R 755 public
  

  确保所有文件具备可读权限。

• 确认触发分支正确性
  配置中only: - master限定仅master分支触发部署，需确认流水线是在master分支上执行的。若在其他分支运行，不会生成Pages部署记录。

• 检查GitLab版本与项目可见性
  若使用自托管GitLab，需确认版本支持Pages功能；私有项目的Pages可能需额外配置访问权限，或存在侧边栏入口显示延迟的情况，可等待一段时间后刷新页面查看。

内容的提问来源于stack exchange，提问作者anslin