GitLab 啟用 Project integration - Mattermost slash commands

日前收到私訊提問,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 WordRequest URLRequest 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 URLRequest 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 的主機其防火牆只開放了 80443 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,防火牆只開放必要的 80443 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 account。

如果是後者「將 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 串接動作就與之前相同了:

  1. 在 Mattermost 新增 Custom slash command。
  2. 在 GitLab Project 的 Settings > integrations > Mattermost slash commands 取得需要填寫至 Mattermost 的 Request URL 等資訊。
  3. 完成 Mattermost Custom slash command 的新增動作,並取得 Token。
  4. 將 Mattermost 提供的 Token 填寫至 GitLab,完成 Mattermost slash commands 的啟用。
  5. 在 Mattermost 上測試方才新增的 slash command,並完成 connect your GitLab account

再次測試一樣可以正常的使用 slash command。

補充說明:無法在 Group 一次為所有 Project 啟用 slash commands

關於串接 slash command,艦長要提醒大家,目前並無法在 Group 層級啟用 Mattermost slash commandsSlack 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 達成目的了。

參考資料

轉貼本文時禁止修改,禁止商業使用,並且必須註明來自「艦長,你有事嗎?」原創作者 Cheng Wei Chen,及附上原文連結。

工商服務

更多文章