概述

Gitlab Pages 的操作和部署简单快速，足以满足日常的在线文档的部署需求，只需要结合 Gitlab Pipeline 即可快速部署，比 Github Pages 还要简单，不信？往下看看🦆 👀。

Gitlab Pages 如何工作

当你在项目的根目录下添加了.gitlab-ci.yml，Gitlab Runner 检索到 yml 这个脚本文件则会执行文件的 Jobs。当我们在脚本中将需要部署的静态文件正确地放入了 public 文件夹，gitlab pages 就会自动部署，部署的域名将会默认分配。

我们需要做的就两件事:

  1. 准备好_.gitlab-ci.ym_l 和 CI/CD 运行环境，在 yml 文件中创建一个名为 pages 的 Job（划重点：固定 Job 名，用于 触发 gitlab pages 的部署）
  2. 转移打包好的目标文件到 public 目录以供 gitlab pages 使用。而 gitlab pages 会到 public目录中解析静态文件生成页面。

社区官方 Gitlab 的默认 pages 域名为 .gitlab.io，是有 *administrator 才有权修改 pages 的默认域名，自定义域名可参考：GitLab Pages custom domains and SSL/TLS Certificates。

设置 Pages 可见性

角色：首先，你得是项目的 Maintainer 及以上的角色，才能控制 Pages 的可见性，否则只能部署，无法修改 Pages 可见性。
位置：控制的开关在 Settings → General → Visibility, project features, permissions，展开后可以看到 Pages 选项

部署 Pages

新增 Pipeline Jobs

根据官方文档，步骤如下：
1. 在.gitlab-ci.yml 中加一个名为 pages 的 job
2. 把页面文件放到 public 文件夹下
3. 把 public 作为 artifacts 的环境路径，放到 gitlab server 中，以便 gitlab pages 使用。

核心脚本：

  1. pages:
  2. script:
  3. - yarn
  4. - yarn docs:build # 文档打包
  5. - rm -rf public
  6. - cp -r docs-dist public # 将 dumi 打包到目标文件的内容移到 public 目录下
  7. artifacts: # 将指定的 path 目录缓存到 gitlab server
  8. paths:
  9.       - public

对核心脚本增加一些配置和限制： 

  1. stages:
  2.   # 新增 stage
  3.   - deploy
  5. variables:
  6.   MAIN_BRANCH: master
  8. # 公用缓存配置
  9. cache: &node_modules_cache
  10.   key: ${MAIN_BRANCH}
  11.   paths:
  12.     - node_modules/
  13.     - packages/*/node_modules/
  15. # gitlab pages deploy job
  16. pages:
  17.   stage: deploy
  18.   cache:
  19.     <<: *node_modules_cache
  20.     policy: pull   
  21.   script:
  22.     - yarn
  23.     - yarn docs:build # 文档打包
  24.     - rm -rf public
  25.     - cp -r docs-dist public # 将 dumi 打包到目标文件的内容移到 public 目录下
  26.   artifacts: # 将指定的 path 目录缓存到 gitlab server（默认30天过期）
  27.     paths:
  28.       - public
  29.   rules:
  30.     - if: $CI_COMMIT_BRANCH == $MAIN_BRANCH # 只作用于 master

在新增 Gitlab Pages 配置时，使用如上脚本即可，原则：
1. 使用 cache 缓存 node_modules 加快 pipeline 运行速度
2. pages 部署只作用于 master

查看是否部署成功

在 Pipeline 中查看 Jobs 的执行情况

注意：There is a magic stage called “pages: deploy” here, which will help deploy your static contents to Gitlab Pages

image.png

查看生成的 public 文件

Gitlab Pages 部署文件放在 public 目录下，莪们通过 artifacts 将 public 上传到了 gitlab server 上， 如果需要查看文档打包结果，有如下两种方式：
1. pipeline 右侧下载
image.png
2. 通过点击 Job 的运作详情，在右方可查看生成的 public 文件夹，可以查看线上 public 目录下的文件，也可下载查看。
image.png

访问 Pages

查看 Pages

Pages Job 执行成功后，在 Settings → Pages 页面下可以看到项目的 Pages 链接，点击即可打开你部署的 Gitlab Pages

如果你的 username/groupname 包含小数点，如生成的 pages 为 https://manqi.lin.git-pages.garena.com/code-common，那么即使你的 pages 部署成功了，你也只能看到 404 页面，这是 HTTP / TLS 协议的限制导致的。

pages 不生效

如果你的 username/groupname 包含小数点，如生成的 pages 为 https://**miki.miki.**[gitlab.io](http://gitlab.io)/my-project，那么即使你的 pages 部署成功了，你也只能看到 404 页面，这是 HTTP / TLS 协议的限制导致的。我们可以尝试在 Settings/Pages 中修改 Domain 相关配置。

Pages 不更新

  1. 查看 Pipeline 是否有 “pages:deploy” 的 Jobs，若没有，可能是你的 yml 脚本有问题
    2. 尝试清楚浏览器缓存，可能是缓存导致页面未更新
    3. pages deploy 可能有延迟，可静候几分钟
    4. 如果有急用，可以先通过当前 job 的 artifacts 访问（如何查看参考上文：查看生成的 public 文件）

参考

Gitlab Pages Docs：https://docs.gitlab.com/ee/user/project/pages/