日前收到私訊提問,GitLab 社群朋友在讓 GitLab 串接 Mattermost slash command 時遇到了一些狀況,但根據艦長的印象,slash command 的背後是直接透過 GitLab API 以 POST 的方式進行串接的,理論上不太會遇到問題。於是好奇心發作的艦長,就頭洗下去的做了一番測試,同時將串接步驟也留做紀錄於本篇文章中。(本文撰寫時,使用的 GitLab 版本為 13.7 。)
(本文同步發表於 Medium。)
過程紀錄
Mattermost 與 GitLab 相同,都可以選擇自架或使用官方提供的 SaaS,因此如果會出現問題,會不會是 Self-hosted 與 Cloud 的問題呢?故此我們會有以下四種串接情境。
- gitlab.com + Mattermost Cloud
- gitlab.com + Self-hosted Mattermost
- Self-hosted GitLab + Mattermost Cloud
- Self-hosted GitLab + Self-hosted Mattermost
上面四種情境要串接 Mattermost slash commands 的操作步驟都是大同小異的,以下就讓我們逐一示範。
gitlab.com + Mattermost Cloud
第一個示範組是最不會出錯的 Cloud SaaS 組合。
在開始設定之前,請先確定你擁有 gitlab.com 與 Mattermost 的足夠權限,GitLab 這邊需要有權限設定 Project 的 Settings;而 Mattermost 則需要管理 Integrations 的權限。
首先在 gitlab.com 上建立一個 Project,並且進入 Settings > integrations
,接著找到 Mattermost slash commands
。
進入 Mattermost slash commands
之後,介面上就會引導使用者該參閱哪一份教學文件。
第一步,我們要進入 Mattermost 的 Main Menu > Integrations > Slash Commands
。
然後按下 Add Slash Command
。
接著有幾個重要的欄位需要填寫,分別是 Command Trigger Word
、Request URL
及 Request Method
。
這三欄該怎麼填呢?GitLab 會告訴你,所以請回到方才在 gitlab.com 開啟的 Mattermost slash commands
介面,會找到類似下圖的各欄資訊,就逐一複製貼上即可。
除了上述三個重要欄位之外,還有 Autocomplete
的各項欄位,也都可以按著 GitLab 介面上的提示逐一填寫。
填寫完畢,就按下 Mattermost 介面上的 Save
,即可獲得一組 Token。
最後將 Token 複製貼上至 GitLab 的介面並 Save changes
就完成了。
回到 Mattermost 的 CHANNELS 介面,試著測試看看,如下圖還沒輸入完指令,Autocomplete 就已經出現提示。
但這時候我們還無法透過它對 GitLab 進行操作,因為我們還需要授權給它操作 GitLab,因此實際執行 slash command 時,會得到下面的提示。
點擊之後,便會進行 GitLab 的 Authorization 動作。
完成授權,再次執行 slash command 就能看到正確的結果,例如我可以直接利用 slash command 新增一個 Issue。
而 BOT 就會回覆我動作執行的結果。
實際點開連結,就能前往 GitLab Project。
以上就是最基本的 GitLab 啟用 Mattermost slash commands
的步驟。當兩邊都採用 Cloud SaaS 時,應該是最不會遇到問題的狀況,只要 Request URL
、Request Method
及 Token 這些有正確填寫,就能正確串接。
補充說明,只要 Mattermost 的管理者新增了 slash command,其他的使用者也同樣能使用此 slash command。唯獨無法省略的是,每個使用者還是要自己完成 GitLab 的 Authorization 動作,才能使用此 slash command。
(想要使用此 slash command 的每位使用者,都需要自行授權。)
如果有正確授權,使用者在自己 GitLab 的 User Settings > Chat
即可看見類似下圖的串接資訊。
gitlab.com + Self-hosted Mattermost
操作步驟與第一個示範「gitlab.com + Mattermost Cloud」相同,理論上也不會遇到問題。
艦長使用 GitLab Omnibus 快速架設了 GitLab Server + Mattermost,接著嘗試讓這個由 GitLab Omnibus 自動安裝的 Self-hosted Mattermost 與 gitlab.com 來串接 Mattermost slash commands
。附帶一提 Self-hosted 的主機其防火牆只開放了 80
與 443
Port。
成功串接之後,在 gitlab.com 這邊的 User Settings > Chat
可以發現,又多了一個 Active chat name,這次的 Nickname 是 root,因為 Self-hosted Mattermost 我是用 root 登入的。
實際測試 slash command,一樣獲得成功建立 Issue 的結果。
Self-hosted GitLab + Mattermost Cloud
這一次左右顛倒,改成 Self-hosted GitLab + Mattermost Cloud。但操作步驟還是與第一個示範「gitlab.com + Mattermost Cloud」相同,理論上也不會遇到問題。
艦長再次使用 GitLab Omnibus 架設了一台乾淨的 GitLab Server,防火牆只開放必要的 80
與 443
Port,依然可以順利的串接 Mattermost slash commands
。
如下圖,同樣的使用者也是需要將自架的 GitLab 與 Mattermost Cloud 進行授權 Connect,才能使用 slash command。
當然成功授權一樣可以在 User Settings > Chat
找到串接資訊。
Self-hosted GitLab + Self-hosted Mattermost
最後輪到都是 Self-hosted 的狀況,如果是自行架設這兩種服務,其實也還要再分為兩種狀況:
- 使用 GitLab Omnibus 在同一個 Server 一次架設這兩項服務。
- 將 GitLab 與 Mattermost 分別架設在不同的 Server 上。
如果是前者,要串接 GitLab 與 Mattermost slash commands
也不太會遇到問題,因為透過 GitLab Omnibus 將 GitLab 與 Mattermost 架設在同一台 Server 時,GitLab 可以更容易的幫你搞定 Mattermost slash commands
的串接設定。
如下圖,這次 GitLab 在 Mattermost slash commands
的 Settings 介面變得不同了,原本應該會顯示多個欄位該如何填寫的,全都消失只剩下 Add to Mattermost
按鈕了。
按下 Add to Mattermost
,會再有一個 install 的介面讓我們可以變更 Command trigger word
。
按下 Install
,結果這次連 Token 都自動幫你填好了。
(完全是懶人模式,連 Token 都自動填好了。)
整個過程完全不用打開 Mattermost,只要在 GitLab 的介面上按一按就搞定了,回到 Mattermost 直接就可以使用此 slash command。
但一樣避不了的,使用者還是要 connect your GitLab accoun
t。
如果是後者「將 GitLab 與 Mattermost 分別架設在不同的 Server 上」的情況,那麼你還是要按一開始介紹的步驟,分別在 GitLab 與 Mattermost 上逐一設定。
GitLab 我們可以透過 GitLab Omnibus 快速架設。那如果想要快速架設 Mattermost 呢?當然就是 Mattermost Omnibus 啦!
Ubuntu 的安裝步驟只有兩行,剩下的安裝包會自動搞定!
curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash
sudo apt install mattermost-omnibus -y
安裝過程,會詢問你要使用的 Domain name 為何。
安裝過程中,Mattermost Omnibus 一樣會貼心的幫你自動申請 Let’s encrypt 免費 SSL 憑證。
看到自動安裝過程中出現了熟悉的 Ansible 執行畫面。
與 GitLab 相同,Mattermost 一架設好,記得要趕快連上它並設定管理者帳號的密碼。
架設完畢後,剩下的 Mattermost slash commands
串接動作就與之前相同了:
- 在 Mattermost 新增 Custom slash command。
- 在 GitLab Project 的
Settings > integrations > Mattermost slash commands
取得需要填寫至 Mattermost 的Request URL
等資訊。 - 完成 Mattermost Custom slash command 的新增動作,並取得 Token。
- 將 Mattermost 提供的 Token 填寫至 GitLab,完成
Mattermost slash commands
的啟用。 - 在 Mattermost 上測試方才新增的 slash command,並完成
connect your GitLab account
。
再次測試一樣可以正常的使用 slash command。
補充說明:無法在 Group 一次為所有 Project 啟用 slash commands
關於串接 slash command,艦長要提醒大家,目前並無法在 Group 層級啟用 Mattermost slash commands
或 Slack slash commands
。各位如果依然按著相同操作步驟,完成在 Group 層級的 Settings > integrations
設定。乍看之下會覺得好像設定成功,且似乎 Mattermost 也能顯示該 slash command,但實際執行它只會得到 404
的錯誤回應。
我們可以仔細看一下 Group 產生的 Request URL
如下:
https://gitlab.com/api/v4/projects//services/mattermost_slash_commands/trigger
若對照 GitLab 的程式碼即可得知,這根本不是一個正確的 GitLab API,因此當 Mattermost 送出 POST Request 給 GitLab 時,當然只會回傳 404 錯誤。
describe 'POST /projects/:id/services/:slug/trigger' do
describe 'Mattermost Service' do
let(:service_name) { 'mattermost_slash_commands' }
context 'no service is available' do
it 'returns a not found message' do
post api("/projects/#{project.id}/services/idonotexist/trigger")
expect(response).to have_gitlab_http_status(:not_found)
expect(json_response["error"]).to eq("404 Not Found")
end
end
這地方就是一個小地雷,因為 Group 層級設定的 Integration 其實是在幫 Group 旗下的 Project 設定 Integration 的預設值,可是目前 Mattermost slash commands
是必須跟著 Project 個別設定的,所以在官方提供更厲害的 API 之前,就先別妄想著能設定一次就讓所有 Project 都能啟用 Mattermost slash commands
。
(其實當你在 Group 層級的 Integration 按下 Save cahgnes
時,GitLab 就會提醒你要注意影響範圍,以及說明這個是 Update the default settings。)
結語
簡短記錄幾個重點:
- GitLab 目前只能在 Project 層級啟用 Integration - Mattermost slash commands,同時能做到的事情並不多,艦長認為比較有可能會在 Mattermost 運用的動作只有 Create new issue、Deploy environment 及 run CI Job。
- 在 GitLab Group 設定的
Settings > integrations
只是在幫 Group 旗下的 Project 設定 Integration 預設值,並無法一次替所有 Project 啟用 slash command。 - slash command 其實就是去呼叫 GitLab API,因此反過來想,如果你熟悉 API,你是有可能用其他方式打造你自己版本的 Mattermost slash command for GitLab,例如透過其它的 ChatBot 工具?
- 只要 Mattermost 的管理者新增了 slash command,全部的使用者就同樣能使用該 slash command。但每位使用者依然要自行在 Mattermost 上
connect your GitLab account
。
最後再補充一些其他資訊:
- Mattermost Cloud 目前開放最多可以 10 人免費使用,有興趣脫離 Slack 的朋友可以考慮看看。
- 在 Mattermost 的 Marketplace 也有一個 GitLab plugin for Mattermost 可以選用,如果對於 GitLab Project integration - Mattermost slash commands 感到失望的朋友,也許可以考慮看看。
最後的最後,當我寫完這整篇文章之後,才發現自己有可能根本犯了一個大錯,那就是根本誤會了社群朋友想問的問題,對方並不是在啟用 Project 的 integration - Mattermost slash commands 遇到問題,反而是想要問「可以如何透過 Mattermost 的 slash command 去 Trigger CI pipeline,有沒有推薦的工具可以使用?」
如果是這個問題,我的回答就如前面的重點第三點,如果只是想要 Trigger CI Pipeline,GitLab 有提供對應的 API,因此你是有可能透過簡單的 ChatBot 工具,做出一個可以在 Slack 或 Mattermost 上做到這件事的 ChatBot。
再者,其實 GitLab Project 的 Integration - Mattermost slash commands,也有一個 command 是 run
,它是能夠 Trigger CI Job 的。因此如果你不想要另外撰寫並架設 ChatBot,那不妨就建立一個「專門用來 Trigger 其他 Project 的 Project」,將 GitLab CI Runner 當作你的自動化控制中心,在該 Project 的 CI Job 中規劃用來 Trigger 其他 Pipeline 的 Job;然後串接該 Project 的 Mattermost slash commands,即可在 Mattermost 上透過 slash command 達成目的了。