JenkinsとGitLabとMattermostを連携する方法

JenkinsとGitLabとMattermostのCI/CDにおける連携設定を備忘録としてまとめました。

[JenkinsとGitLabを連携する方法](https://qiita.com/takamii228/items/3598f403518c296f93f3)の続きです。

以下、JenkinsとGitlabの連携は済んでいる前提で手順を説明します。

# 1. Mattermost Pluginのインストール

Jenkinsに[Jenkins Mattermost Plugin](https://github.com/jenkinsci/mattermost-plugin)をインストールします。
インストールは管理者権限のあるユーザでJenkinsにログインし、`Jenkinsの管理`→`プラグインの管理`→`利用可能`なタブを選択、Mattermost Pluginにチェックをいれてインストールを実行します。

# 2. MattermostのIncoming Webhook設定

Mattermostの管理者権限のあるユーザでログインし、左上のハンバーガーメニューから`Integrations(統合機能)`を選択し、`Incoming Webhook(内向きのウェブフック)`をクリックします。

もし`Incoming Webhook(内向きのウェブフック)`がない場合は、`System Console(システムコンソール)`の中の`INTEGRATIONS(統合機能)`→`Custom Integrations(カスタム統合機能)`の中の`Enable Incoming Webhooks(内向きのウェブフックを有効にする)`を`true(有効)`にすると出てきます。
また、以下も`true(有効)`にしておきましょう。

* `Enable integrations to override usernames(統合機能によるユーザー名の上書きを許可する)`
* `Enable integrations to override profile picture icons(統合機能によるプロフィール画像アイコンの上書きを許可する)`

右上の`Add Incoming Webhook(内向きのウェブフックを追加する)`を選択し、以下を入力します。

- Display Name(表示名) : 通知の投稿の表示名を設定
- Description(説明) : WebHookの内容説明を記載
- Channel(チャネル) : デフォルトで通知を出すチャネルのURIを設定(Jenkins、Gitlab側で上書き可能です)

`save(保存する)`を押すとWebhook用のURLが発行されます。

# 3. Jenkins側のMattermost設定

管理者権限のあるユーザでJenkinsにログインし、`Jenkinsの管理`→`システムの設定`を選択し、`Global Mattermost Notifier Settsings`の以下の項目を設定します。

- Endpoint : 先ほど発行したMattermostのWebhookのURLを設定
- Channel : 指定があればチャネルのURI名（チャネル名ではないので注意）、複数指定する場合はカンマ区切り
- Icon to use : アイコンとして利用するavatarの画像URL
- Build Server URL : JenkinsのURL

`Test Connection`を押して`Success`が表示され、Mattermost側に以下が表示されればOKです。

```
Mattermost/Jenkins plugin: you're all set! (parameters: endpoint='xxx', room='yyy', icon='zzz', buildServerUrl='www')
```

ここでの設定はグローバルでの設定で、各プロジェクトで個別に設定することも可能です。その場合はJenkinsfile側で設定します（上書き扱いになる）。

# 4. Gitlab側のMattermost設定

GitLabの対象のレポジトリのMaster権限のあるユーザでログインし、レポジトリの`Settings`→`Integrations`を選択し、`Project services`の中の`Mattermost notifications`を選択して以下を入力します。

- Active : チェックする
- Trigger : 通知対象のイベントにチェックをつけ、通知対象のチャネル名を必要であれば設定する(1での設定が上書きされます)
	- Push
	- Issue
	- Confidential issue
	- Merge request
	- Note
	- Tag Push
	- Pipline
	- Wiki page
- Wehhook : 1で発行したMattermostのWebhookのURLを設定
- Username : Mattermostでの通知のときのユーザ名を設定
- Notifiy onley broken piplines : 必要に応じてチェック
- Notifiy onley default branch : 必要に応じてチェック

入力後に`Save changes`を押して、`Test settings`を押し、上部に青く`We sent a request to the provided URl`が表示されれば成功です。
失敗する場合はWebhookのURLや環境疎通を確認してみてください。

※iconのパラメータは現状設定できないため、Mattermost上ではWebhookのiconになります。

# 5. Jenkinsfileの設定と動作確認

Jenkinsのジョブの定義はJenkinsfileで定義します。Jenkinsのジョブが成功・失敗したときに通知するJenkinsfileのサンプルを置きました。対象のレポジトリのJenkinsfileに以下を記載して、レポジトリへPushしてみましょう。

```groovy
pipeline {
    agent any

    post {
        success {
            updateGitlabCommitStatus name: 'build', state: 'success'
            updateGitlabCommitStatus name: 'test', state: 'success'
            updateGitlabCommitStatus name: 'deploy', state: 'success'
            mattermostSend color: "good", message: ":smile: [${env.JOB_NAME}](${env.BUILD_URL}) のビルドOK"
        }
        failure {
            updateGitlabCommitStatus name: 'build', state: 'failed'
            updateGitlabCommitStatus name: 'test', state: 'failed'
            updateGitlabCommitStatus name: 'deploy', state: 'failed'
            mattermostSend color: "danger", message: ":dizzy_face: [${env.JOB_NAME}](${env.BUILD_URL}) のビルドに失敗しました", text: "@channel"
        }
    }

    options {
        gitLabConnection('Gitlab')
        gitlabBuilds(builds: ['build', 'test', 'deploy'])
    }

    triggers {
        gitlab(
            triggerOnPush: true,
            triggerOnMergeRequest: true,
            branchFilterType: 'All',
            addNoteOnMergeRequest: true,
            addCiMessage: true
        )
    }

    stages {
        stage('build'){
            steps {
                echo "BUILD"
            }
        }
        
        stage('test'){
            steps {
                echo "TEST"
            }
        }

        stage('deploy'){
            steps {
                echo "DEPLOY"
            }
        }
    }
}
```

GitLabへのPush、JenkinsのBuildの二つの通知がMattermostに連携されれば成功です。

GitLabのPushのイベントに関しては以下の形式でMattermostに通知されます。

```txt
[username] pushed to branch master of [username]/[branch name] (Compare changes)

[commit id]: [commit massege] - [username]
```

Jenkinsの通知メッセージは`mattermostSend`で設定したパラメータ、メッセージで内容が表示されます。↑の例の場合は以下のようになります。

```txt
:smile: [${env.JOB_NAME}](${env.BUILD_URL}) のビルドOK
```

# 補足

mattermostSendのパラメータは以下の内容がカンマ区切りで指定可能です。

- `message` : 通知で表示するメッセージ内容、環境変数を含めることができる。
- `channel`(optional) : 通知するMattermostのチャネルのURI名（チャネル名ではないので注意）
- `color`(optional) : good / warning / danger / or hex color codeで、通知メッセージのボックスの色が指定できます。
- `endpoint`(optional) : MattermostのWebhookのURL
- `failOnError`(optional) : trueにした場合はメッセージが表示されてWorkflowがabortされます
- `icon`(optional) : iconの画像URL。設定した場合はグローバル設定が上書きされる
- `text`(optional) : messageの後に続くテキスト、メンション情報はここに定義する

# 参考情報

- https://github.com/jenkinsci/mattermost-plugin
- https://jenkins.io/doc/pipeline/steps/mattermost/
- https://jenkins.io/doc/book/pipeline/syntax/
- https://www.mattermost.org/webhooks/
- https://docs.gitlab.com/ee/user/project/integrations/mattermost.html