GitLab 页面预览

教程
GitLab

在撰写关于Apache APISIX的博客文章时，我希望同事们能先行审阅。但鉴于我的博客内容兼收并蓄，既有个人随笔也有业务分享，我不想将这些文章直接存入仓库。我需要一种仅限少数人预览的方式，类似于Vercel的预览功能。我目前使用的是GitLab Pages，但它并不提供现成的此类功能。

I tried two methods: GitHub gists and PDFs. Both have issues.

虽然Gists能提供代码片段分享，但其展示效果远不及最终网页。为此，我尝试了DocGist，它虽有所改进，却并非万能解决方案。

此外，Gists无法显示图片，因为我采用Asciidoc编写文章。我不得不将图片置于评论中，这打断了文章的连贯性。我曾尝试将图片附加到gist，但无论如何，图片都无法自然融入文章正文。评论的优点在于有序，缺点则是我必须修改Asciidoc源码。

I used gists because I’m used to GitHub reviews. But since it’s my blog, I neither need nor want the same kind of reviews as in a regular Merge Request. I need people to point me to when something needs to be clarified or I missed a logical jump, not that I made a typo (I use Grammarly for this). For this reason, a PDF export of a post is enough to review.

然而，PDF格式也有其固有问题：网页内容可无限延伸，而PDF则将其分割成标准页面，可能导致图表跨页分割。此外，PDF格式的分发也更为困难。

本文将详细介绍我是如何配置GitLab Pages以实现所需的预览效果。

GitLab Pages概述

GitLab Pages与GitHub Pages类似：

利用GitLab Pages，您可以直接从GitLab中的仓库发布静态网站。

要通过Pages发布网站，您可以使用任何静态网站生成器，如Gatsby、Jekyll、Hugo、Middleman、Harp、Hexo或Brunch。您还可以发布直接使用纯HTML、CSS和JavaScript编写的任何网站。

— GitLab Pages

这就是您看到这篇博文的方式。我未能在GitLab Pages中发现预览功能。尽管向专家咨询，但GitLab并不提供预览功能。

规划工作

I didn’t believe it initially, but you only need to create a dedicated artifact. Since the artifact consists of web files, the browser will render them.

构想是创建一个可通过URL访问的工件，且该URL不易被轻易预测。随后，我可以将URL分享给同事并请求他们的审阅。首先，我们可以复制现有master上的构建：

YAML

  

stages:
  - preview

preview:
  stage: preview
  image:
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
  before_script: cd /builds/nfrankel/nfrankel.gitlab.io
  script: bundle exec jekyll b --future -t --config _config.yml -d public
  artifacts:
    paths:
      - public
  only:
    refs:
      - preview
  variables:
    JEKYLL_ENV: production

此时，网站可在https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html访问。然而，仍有许多问题需要解决。

解决问题

让我们按重要性顺序逐一解决这些问题。

修复访问权限

该项目为私有，因此只有我能访问该工件：这与最初提供预览给其他人的目的相悖。

I want to give my teammates only limited access to my GitLab repository. I gave them Guest access, according to the Principle of least privilege. However, it still didn’t work.

根据文档，您还必须将您的流水线设置为公开。前往设置 > CI/CD > 通用流水线，勾选“公开流水线”复选框。

修复相对链接

I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:

  • 例如，通过url设置的域名，例如，
  • 路径，例如，/，与设置的baseurl

在预览中显示不同。必须在YAML配置文件中设置这些参数；没有环境变量替代方案。

让我们相应地调整构建：

YAML

  

preview:
  stage: preview
  image:
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
  before_script:
    - cd /builds/nfrankel/nfrankel.gitlab.io
    - "printf 'url: https://%s.gitlab.io\n' $CI_PROJECT_NAMESPACE >> _config_preview.yml"                        #1
    - "printf 'baseurl: /-/%s/-/jobs/%s/artifacts/public/\n' $CI_PROJECT_NAME $CI_JOB_ID >> _config_preview.yml" #2
    - cat _config_preview.yml                                                                                    #3
  script: bundle exec jekyll b --future -t --config _config.yml,_config_preview.yml -d public                    #4

  1. 使用CI_PROJECT_NAMESPACE环境变量设置url。虽然它是不变的，本可以使用硬编码值，但这样脚本更易于复用
  2. 使用CI_PROJECT_NAME和CI_JOB_ID环境变量设置baseurl。后者是需求中的随机部分
  3. 为了调试目的，显示配置内容
  4. 使用它！

提升可用性

每次都要分发正确的URL实在麻烦。最好在构建后在控制台中记录下来：

YAML

  

after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html

还有一个遗漏的部分。GitLab Pages提供了一个索引页。例如，如果你请求https://blog.frankel.ch，它们会提供根目录index.html。使用普通构件时并非如此。鉴于我只想提供单篇预览文章，这不成问题，因此我没有进一步研究配置。

使用方法

此时，我只需将更改推送到我的preview分支：

Shell

  

git push --force origin HEAD:preview

锦上添花的是，我们无需本地分支；只需推送到远程分支即可。

结论

在这篇文章中，我展示了如何预览GitLab Pages，并通过几个步骤与团队成员分享预览链接。最难的部分是意识到网页工件通常是通过浏览器进行渲染的。

深入探讨：

Source:
https://dzone.com/articles/gitlab-pages-preview