GitLab 切換到 https 的紀錄


Heresy 之前自己架的 GitLab Server 的時候,由於是純對內的服務、沒有對外連線,所以要使用 GitLab 內建的 Let’s Encrypt(官網)來取得 SSL 憑證有點難度,所以當時就決定先用 http 來跑、而沒有用 https 了。

後來,手邊其實也有對應網域的 SSL 的憑證了,GitLab 的 SSL 設定也研究得差不多了(官方文件),所以就決定花點時間、把他從走 8080 port 的 http 轉換到標準的 443 port https 了。

而這篇,就是轉換的一些紀錄。


GitLab 設定檔修改

由於 Heresy 用的是 Docker 的版本,所以要參考的是官方「Omnibus-GitLab」的設定。

這邊主要就是要修改容器內的 /etc/gitlab/gitlab.rb 這個設定檔;而如果是要在容器外修改的話,以 Heresy 當初的設定,就是修改 /mnt/gitlab_data/config/gitlab.rb 這個檔案。

修改的內容主要是下面三行(在不同的位置):

external_url 'https://gitlab.heresy.tw'

registry_external_url 'https://gitlab.heresy.tw:5100/'

letsencrypt['enable'] = false

其中第一行的「external_url」是設定對外服務的網址,這邊 Heresy 之前的設定是「http://gitlab.heresy.tw:8080」這種非常規的設定。

第二行的「registry_external_url」則是 GitLab 內建的 Docker Registry 的對外連線設定,這邊也是從 http 改成 https。

第三行的部分,則是把內建、預設開啟的 Let’s Encrypt 整合關閉,這樣才能使用自己的憑證。


設定 SSL 憑證

GitLab 的 SSL 憑證檔案配置方法很簡單,只要在容器內的 /etc/gitlab 下,建立一個 ssl 資料夾,並把權限設定成 755,然後把憑證檔案(crt 和 key)放進來就可以了。

官方教學的指令是(注意:這邊是在 GitLab 容器內):

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp gitlab.example.com.key gitlab.example.com.crt /etc/gitlab/ssl/

其中,憑證的檔名是要改成網域名,以 Heresy 的例子來說,就是改成「gitlab.heresy.tw.crt」、「gitlab.heresy.tw.key」的形式。


處理 SSL 憑證

理論上憑證檔案是放進去就好了。不過,Heresy 這邊拿到的 SSL 憑證(應該是針對 Apache 的),基本上都是三個檔案的形式:

  • 憑證檔案(STAR.heresy.tw.crt)
  • 密鑰(STAR.heresy.tw.key)
  • intermediate certificate(bundle.crt)

如果只拿前面兩個檔案來用的話,雖然 GitLab 的網頁會是正常的,但是在用 https 進行 git 的操作的時候,則是會出現下面的錯誤:

fatal: unable to access 'https://gitlab.heresy.tw/test/test.git/':
 SSL certificate problem: unable to get local issuer certificate

這個問題其實和 Heresy 之前在用 Boost ASIO 建立 WebSocket Server 的時候類似,是沒有正確設定那個 bundle.crt 的關係。

GitLab 這部分的設定,基本上應該是基於 NGINX 來做設定,找了一下後,後來是參考《nginx + SSL Certificate – 讓 http 變身成為 https》這篇的方法,來將「STAR.heresy.tw.crt」和「bundle.crt」這兩個檔案合併,這樣就可以了。

這邊比較簡單的操作方法是透過下面的指令來完成:

cat STAR.heresy.tw.crt bundle.crt >> gitlab.heresy.tw.crt

然後把合併完成的 gitlab.heresy.tw.crt 這的檔案放到 /etc/gitlab/ssl 裡面就可以了。


重新進行 GitLab 組態設定

上面的步驟完成後,接下來只要讓 GitLab 重新跑一次組態設定就可以了。

這邊最簡單的方法,是直接重啟整個 GitLab Docker:

docker restart gitlab

不過這樣的缺點,是如果有設定有錯誤導致無法正確啟動的話,也看不到錯誤訊息、只會看到容器不停地在重啟。

如果想看他重新進行組態設定的過程的話,也可以執行:

docker exec gitlab gitlab-ctl reconfigure

這樣一來是比較快、二來則是可以看到過程中的輸出、並發現問題了。

理論上這樣就完成了,但是這邊也要注意當時建立 GitLab 容器的時候的 port mapping,可能會需要做對應的調整。

像 Heresy 這邊最後的 port mapping 是:

-p 443:443 -p 8080:443 -p 80:80 -p 5100:5100

這邊也把本來使用的 8080 port 對應到新的 443 port,主要是要做相容了。


http 轉換到 https 的影響

這樣修改完後,對於既有的環境有什麼影響呢?主要有:

網頁端

  • 由於 GitLab 預設會把 http 重新導向到 https,8080 也對應回 443 了,所以就算用舊的網址來連線,大多也都可以使用,也因此,在網頁端的問題並不大。
  • 但是如果有使用整合的 PlantUML(參考)或 Kroki(參考)這類的繪圖服務的話,就得把這些服務也從 http 改成 https,否則會沒辦法看到產生的圖片了。
    • 而像 Kroki 本身不支援 https 的模式,所以還需要用 NGINX 來做反向代理,這部分之後再整理了。

GitLab Runner

GitLab Runner 的部分,由於在設定時是針對本來的 GitLab 網址設定的,在轉換到 https 後,GitLab Runner 也得做對應的修改。

一個當然是取消本來的連線、直接重建,但是相對地會比較麻煩。

所以比較簡單的方法,就是去修改 gitlab-runner 的設定檔 config.toml參考),把裡面的網址改掉、然後重新啟動 GitLab Runner。

Windows 的檔案會和執行檔在一起,Linux 則是會放在 /etc/gitlab-runner/config.toml

用戶端的 Git Repository 修改

比較麻煩的可能是這個了…

使用者如果已經有把 GitLab 上的 repository clone 下來的話,裡面的網址也會是舊的,而且沒辦法透過自動導向來運作。

所以變成每一個本機上的 repository 都得手動修改 url(submodule 也得改),如果數量多的話,真的很麻煩…


這邊大概就這樣了,理論上 Heresy 這邊事都處理好了。如果之後有碰到相關問題,就在另外紀錄了。

對「GitLab 切換到 https 的紀錄」的想法

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com 標誌

您的留言將使用 WordPress.com 帳號。 登出 /  變更 )

Google photo

您的留言將使用 Google 帳號。 登出 /  變更 )

Twitter picture

您的留言將使用 Twitter 帳號。 登出 /  變更 )

Facebook照片

您的留言將使用 Facebook 帳號。 登出 /  變更 )

連結到 %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.