GitLab 頁面預覽

教學
GitLab

當我撰寫與Apache APISIX相關的部落格文章時，我希望我的同事們能先行審閱。但這是我的個人部落格，由於我混合了個人與商業內容，因此我不希望將它們納入版本庫。我需要一種僅供少數人預覽的方式，類似於Vercel的預覽功能。我正在使用GitLab Pages，但這裡並沒有現成的此類功能。

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

Gists的展示效果不如最終網頁精美。我試圖透過使用DocGist來改善這種情況。雖然有所改進，但仍非萬全之策。

此外，由於我使用Asciidoc撰寫文章，Gists無法顯示圖片。我必須將圖片設置在註釋中，這會打斷閱讀的流暢性。我曾嘗試將圖片附加到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並與隊友分享預覽的URL。最困難的部分是理解網頁工件通常是使用瀏覽器進行渲染的。

進一步探討：

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