Jenkins
CI
GitLab
Mattermost

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

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

JenkinsとGitLabを連携する方法の続きです。

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

1. Mattermost Pluginのインストール

JenkinsにJenkins 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権限のあるユーザでログインし、レポジトリのSettingsIntegrationsを選択し、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してみましょう。

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に通知されます。

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

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

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

: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の後に続くテキスト、メンション情報はここに定義する

参考情報