使用 GitLab Pages 建立靜態網站

12 min readJan 10, 2021

（2021/12/25 註記：左思右想，決定棄用 Medium，未來更多文章請參閱 https://chengweichen.com）

（本文的 Canonical URL —https://chengweichen.com/2021/01/use-gitlab-pages-host-static-website.html）

身為 GitLab Hero，善用（應該要用） GitLab Pages 來建立靜態網站也是理所當然的事情，之前都是把個人網頁放在自己長期租用的 VPS 上，但最近想要省一點錢，決定把 VPS 砍了，將靜態網站通通都搬到 GitLab Pages 上，所以本文就拿 chengweichen.com 作為案例，實際示範一遍給大家看。（本文撰寫時，使用的 GitLab 版本為 13.7 。）

過程紀錄

根據 GitLab 官方文件的說明，GitLab Pages 目前可以在 gitlab.com 上免費使用（既使該靜態網站是為了商業用途也可以免費使用），同時 GitLab Pages 也支援 HTTPS 及 Custom domain。因此我那個沒啥流量的個人網頁，是完全能夠以 GitLab Pages 架設的。

架設步驟十分簡單，首先是事前準備：

（非必要）準備好你的 Custom domain，如果你沒有自己的網域名稱，GitLab 也有免費提供如 xxx.gitlab.io 的預設子網域名稱可直接套用。

【小提醒】xxx.gitlab.io 其中的 xxx 其實是你 GitLab Project 的 Namespace。以下圖為例，我的 Project namespace 就是 chengwei.chen。

如果你想要使用 GitLab 免費提供的預設網域，同時又想要 GitLab 幫你自動使用免費的 SSL 憑證來啟用 HTTPS，那必須要注意該 Project 的 Namespace 不可以有 .。就如上圖的 chengwei.chen 就是一個會導致無法啟用 HTTPS 的 Namespace，對於此種狀況 GitLab 在 WebUI 上也會提醒並解釋原因讓使用者知道。

其實有在使用 Let’s Encrypt 這個免費 SSL 憑證，並且有嘗試申請過 wildcard certificates 的朋友就會知道原因。簡單來說這和網域名稱是用 . 來分隔有關，每多一個 . 就是多一層的 subdomain，所以可以想見 GitLab 早已申請了 *.gitlab.io 的 Wildcards certificates 套用在所有 GitLab Pages 上；而我上面範例中 chengwei.chen 這個 Namespace 在套用之後會變成 chengwei.chen.gitlab.io，理所當然不適用於 *.gitlab.io 這個 Wildcards certificates。
最終，為了啟用 HTTPS，我另外建立了一個名為 chengweichen-website 的 GitLab Group，如此一來 Namespace 就變成 chengweichen-website，即可順利啟用 HTTPS 套用在 chengweichen-website.gitlab.io。

（非必要）準備好你的 SSL 憑證，如果你不想用 Let’s Encrypt 這種免費的 SSL 憑證，你也可以自己準備更高級的 SSL 憑證給 GitLab Pages 使用。
準備好靜態網站的原始檔。

接著按著這篇 2016 年的官方教學來操作：

第一步，先建立一個乾淨的 GitLab Project。

當然如果你的靜態網站和艦長一樣，檔案原本是放在 GitHub 上，那可以利用 Import project 直接匯入至 GitLab。（GitLab 官方當然早就準備好搬家指南啦。）

另外，提醒大家在新增 Project 時，有一項設定是你可以多加考慮的，那就是 Project visibility。

GitLab 目前開放即便是 Private project 也可以利用 GitLab Pages 建立公開的靜態網站，因此如果你不喜歡自己網站的原始檔，全都直接暴露被人看光光的話，你可以直接將 Project visibility 設為 Private。

又或者，你也可以選擇將 Project visibility 設為 Public，但設定 Repository 這個功能是 Only Project Members，即是只有該 Project 的 Member 才能檢視 Repository，如此同樣能避免閒雜人等隨便瀏覽你的靜態網站原始檔。

如下圖，Visibility 是 Public 但 Repository 是 Only Project Members 的 Project，對方只會得到 404，是無法查看 Project 內容的。

總之在 Project 的 Settings > General > Visibility, project features, permissions 之下有許多選項，務必根據你的需求詳細設定，你可以把用不到的功能關閉或一一修改為只有 Project Member 才能使用；最後小提醒一下，Pipelines 這個功能要保持啟用，因為我們需要 CI Pipeline 幫我們打包 Artifacts 並提供給 GitLab Pages 使用。

（Pipelines 一定要啟用，但你可以限制它 `Only Project Members`。）

第二步，為你的 Project 新增 CI/CD Pipeline。即是新增一個 .gitlab-ci.yml 並塞入以下的內容。

pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

從官方範例可以發現這個 Pipeline 做的事情很單純，就是建立一個 .public 資料夾，並將 Project 所有的檔案複製一份到 .public 內，最後再將資料夾重新命名為 public，然後將 public 的檔案建立為 Artifacts。

但其實也不用這麼麻煩，你可以打一開始，在 Project 中就是將靜態網站的所有檔案放在 public 之下，然後將其建立為 Artifacts。所以我的 .gitlab-ci.yml 可以精簡如下。

pages:
  stage: deploy
  script:
  - echo "Do Nothing!"
  artifacts:
    paths:
    - public
  only:
  - master

第三步，將網站原始檔放進 Project。如果你的 Project 還是空白沒資料的，那現在可以將你的靜態網站內容丟進 GitLab Project。當然如果你一開始就是從 GitHub 搬家過來的，這一步就可以跳過了。Git 的相關操作這邊就不一一教學了，總之就是使用 Git 將靜態網站內容 Commit 並 Push 至 GitLab Project 內。

第四步（非必要），設置你的 Domain name。

前面有提過如果你沒有自己的網域名稱 Domain name，那麼可以使用 GitLab 預設分配的 xxx.gitlab.io。如果想要讓靜態網站套用自己的網域名稱，則可以在 Project 的 Settings > Pages 找到 New Domain 的按鈕，點擊後即可為 Pages 設置你自己的網域名稱。

如下圖，在 New Domain 的同時，也可以同步設定是否要讓 GitLab 自動幫你申請 Let’s Encrypt 的免費 SSL 憑證。即便是自己的網域名稱也能自動申請。

設置完 GitLab 這一端，接著我們還要回到自己的網域供應商，去新增對應的 DNS Record，如此才能正式讓 Pages 套用我們自己的網域名稱。

如下圖，要設置的 DNS Record 會有兩項，一項為 A 或 CNAME Record，另一項則是 TXT Record。

先解釋 TXT Record，這是用來驗證你確實擁有此網域名稱的所有權，通過驗證後 GitLab 才會完成網域名稱導向 Pages。

至於 A 或 CNAME Record，在 GitLab 的教學文件中，是教大家設置 A Record。

但從上圖你也可以看見，該教學文件曾經更新過一次，將 A Record 的 IP 更換了。而目前 Pages 的 Settings 介面，則都是顯示 CNAME Record。A 與 CNAME 的詳細差異與運作原理就是 DNS 的相關知識了，有興趣深入了解的朋友可以參閱 Wiki 或其他 DNS 教學資源。

【小提醒】如果你想要設定的網域名稱非子網域，例如 about.chengweichen.com。而是和艦長一樣，欲採用裸域名，例如 chengweichen.com，那你在嘗試為裸域名設置 CNAME 時，有可能會遇到網域供應商不給設定的狀況。比較簡單的解法就是如 GitLab 的教學文章一樣，以 A Record 將裸域名對映到 GitLab Pages server 的 IP。至於為何不能替裸域名設置 CNAME 呢？這一樣是 DNS 領域的相關知識了，有興趣的朋友可以參閱前面提及的 DNS 教學資源。

剛設置好的 Domains 並不會馬上就啟用 HTTPS，一開始只能用 http:// 連上。

（如上圖，我又為 Pages 新增了 `about.chengweichen.com` 這個 Subdomain，一開始就只有 `http://`。）

第五步（非必要），設置你自行準備的 SSL 憑證。

在上一個步驟其實就有提到，GitLab Pages 可以自動幫你申請免費 SSL 憑證 Let’s Encrypt，但如果你不想要也可以使用自己另外購買的 SSL。

如下圖，只要將 Automatic certificate management 的設定關閉，就會出現輸入 Certificate (PEM) 與 Key (PEM) 的欄位。

結語

只要按著教學文件的步驟，基本上將靜態網站交由 GitLab Pages 來替你 host 可說是毫無難度。其中我覺得比較有可能遇到問題的即是 Namespace、Project visibility、以及裸網域無法設置 CNAME 的狀況，但也都不是太難解決的問題。如果你也是 GitLab 的愛好者，同時也有一些沒有流量的靜態網站，不妨就將網站交給 GitLab Pages 吧。

假如你的靜態網站是使用 Jekyll、Hexo、Hugo 這一類靜態網站產生器（Static Site Generator）產生的，你同樣也能使用 GitLab Pages 來 host 它們。差別只在於務必正確的撰寫 .gitlab-ci.yml，讓 GitLab CI 能幫你自動完成 Generator 並將產出結果放置於 public，最後記得打包成 Artifacts 供 GitLab Pages 使用即可。

最後再補充說明一點，雖然在 2016 年的那篇 GitLab Pages 教學文件中沒有提供 Hugo 的 .gitlab-ci.yml 範例，但現在官方已直接釋出了多個 GitLab Pages 的 Example projects，上面有各種範例可以參考，當然也包含了 Hugo 及其他各種常見的靜態網站產生器，不知道該如何開始的朋友，可以直接參考這些 Example。

使用 GitLab Pages 建立靜態網站

過程紀錄

結語

參考資料

Written by Chengwei Chen

No responses yet