Jenkins
CI
GitLab

JenkinsとGitLabを連携する方法

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

1. GitLabプラグインのインストール

JenkinsにJenkins GitLab Pluginをインストールします。
インストールは管理者権限のあるユーザでJenkinsにログインし、Jenkinsの管理プラグインの管理利用可能なタブを選択、GitLab Pluginにチェックをいれてインストールを実行します。

2. Jenkins側のGitLabの認証設定

JenkinsからGitLabのレポジトリやジョブの実行結果を連携するために、JenkinsにGitLabの認証情報を設定します。

GitLabのAccess Tokenの取得

GitLabのAPIキーは、CI/CDの対象となるレポジトリのDeveloper権限以上をもつユーザのものが必要です。

APIキーはGitLabにログインし、右上のSettingsAccess Tokensから発行ができます。

Name(名前)Expires at(有効期限)Scopes(api、read_user)を選択してCreate personal access tokenを選択してAccess Tokenを発行します。
するとYour New Personal Access Tokenのところに英数字に文字列がでるので、コピーしておきます。このトークンは二度と表示されないため、保存に失敗した場合は再発行してください。

グローバルドメインの設定

さきほど取得したAPIのAccess TokenをJenkinsの認証情報として保存します。

Jenkinsのメニューの認証情報Systemグローバルドメインを選択、左にある認証情報の追加を選択し、以下の内容で追加します。

  • 種類 : GitLab API token
  • API token : さきほど発行したGitLabのAccess Token
  • ID : 空欄(あとで自動発行される)
  • 説明欄 : GitLab認証用のAPIトークンである旨の説明を記載

続けて、同じ要領でAccess Tokenを発行したユーザの認証情報も登録します。

  • 種類 : ユーザ名とパスワード
  • ユーザ名 : GitLabのユーザ名
  • パスワード : GitLabのパスワード
  • ID : 空欄(あとで自動発行される)
  • 説明欄 : GitLab認証用のユーザである説明を記載

Jenkins GitLab Pluginの設定

次にGitlabのドメイン認証設定をします。

Jenkinsの管理システムの設定を選択し、GitLabのところを設定します。設定値は以下の通りです。

  • Enable autehntication for '/project' end-pointにチェック
  • Gitlab connections
    • Connection name : Jenkins内部で識別するGitLabのコネクション名(例: GitLab)
    • GitLab host URL : GitLabのURL
    • Credentials : グローバルドメインで設定したGitLabのAccess Token

高度な設定ではAPIレベルの指定、SSL証明書のエラー無視の有無、コネクションタイムアウト秒数、リードタイムアウト秒数が設定できますが、ここではデフォルトのままにします。

すべて設定した後にTest Connectionを押し、Successが出れば認証設定は完了なので、保存を押して設定を保存します。

3. Jenkinsのパイプラインジョブ作成

今回はbranch pushによるCI/CDを実現するために、Multibranch Pilineでジョブを定義します。

左のメニューの新規ジョブ作成を選択し、Enter an item nameのところにジョブ名を記載し、Multibrancn Pipelineを選択してOKを選択します。

ジョブの詳細設定は以下のように設定します。

  • General
    • フォルダ名 : 前の画面で設定したジョブ名(URIに利用されます)
    • 表示名 : 表示名を設定
    • 説明 : ジョブの説明を記載
  • Branch Sources
    • Gitを選択
    • プロジェクトレポジトリ : GitLabのgit cloneのアドレス(最後が.gitのやつ)を記載
    • 認証情報 : さきほど設定したGitLabのユーザ名・パスワードの認証情報を選択
    • Behaviours : Discovery branches(デフォルトのまま)
    • Property strategy : All branches get the same propeties(デフォルトのまま)
  • Build Configuration
    • Mode : by Jenkinsfile
    • Script Path : gitレポジトリ内のJenkinsファイルのパス(ルートならJenkinsfileと記載)
  • その他の設定※
    • Scan Multibranch Pipline Triggers
    • 不要アイテムの扱い
    • 健全性のメトリクス
    • Propetries
    • Pipeline Librares
    • Pipeline Model Definition

※その他の設定は今回はデフォルトのまま行います、必要に応じて設定してください。

設定が完了すると、対象のレポジトリのスキャンが始まり、Jenkinsfileの確認が実行されます。

定義したジョブをクリックして、Scan Multibranch Pipeline Logの最後が以下のようにFinished: SuccessになればOKです。

Branch indexing
[Tue Mar 13 07:17:49 UTC 2018] Starting branch indexing...
 > git --version # timeout=10
using GIT_ASKPASS to set credentials xxxxxx
 > git ls-remote --symref https://xxxxxxxxxxx/yyy/zzz.git # timeout=10
 > git rev-parse --is-inside-work-tree # timeout=10
Setting origin to https://xxxxxxxxxxx/yyy/zzz.git
 > git config remote.origin.url https://xxxxxxxxxxx/yyy/zzz.git # timeout=10
Fetching & pruning origin...
Fetching upstream changes from origin
 > git --version # timeout=10
using GIT_ASKPASS to set credentials xxxxxx
 > git fetch --tags --progress origin +refs/heads/*:refs/remotes/origin/* --prune
Listing remote references...
 > git config --get remote.origin.url # timeout=10
using GIT_ASKPASS to set credentials xxxxxx
 > git ls-remote -h https://xxxxxxxxxxx/yyy/zzz.git # timeout=10
Checking branches...
  Checking branch master
      ‘Jenkinsfile’ found
    Met criteria
Changes detected: master (aaaaaaaaaaaaaaaaaaaaaaa → bbbbbbbbbbbbbbbbbbbb)
Scheduled build for branch: master
Processed 1 branches
[Tue Mar 13 07:17:50 UTC 2018] Finished branch indexing. Indexing took 0.96 sec
Finished: SUCCESS

4. GitLabのWebhook設定

次にGitLabのレポジトリへのPushやMerge RequestのイベントトリガーでJenkinsが実行されるようにWebhookの設定を行います。

GitLabにJenkinsに設定したユーザでログインし、対象のレポジトリにアクセスしてメニューからSettingsIntegrationsを選択します。

以下のパラメータを入力してAdd webhookをクリックして設定します。

  • URL : https://[JenkinsのユーザID]:[JenkinsユーザのAPI Token]@[JenkinsのホストURI]/project/[Jenkinsのジョブ名]
    • JenkinsのユーザIDJenkinsユーザのAPI Tokenは、Jenkinsにログインして右上のユーザ名をクリックし、設定APIトークンAPIトークンの表示で確認できます。
  • Secret Token : 空欄
  • Triggers
    • Push events, Merge Request events, Job events, Pipeline eventsにチェックを入れます。必要に応じてチェックを追加してください
  • SSL verification
    • チェックします(必要に応じてチェックを外してください)

設定後にTestをクリックしてHook executed successfully: HTTP 200が返ってこれば成功です。エラーになった場合は認証情報や接続情報を見直してみてください。

5. 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'
        }
        failure {
            updateGitlabCommitStatus name: 'build', state: 'failed'
            updateGitlabCommitStatus name: 'test', state: 'failed'
            updateGitlabCommitStatus name: 'deploy', state: 'failed'
        }
    }

    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"
            }
        }
    }
}

Push完了後にJenkinsのジョブが自動で実行され、実行結果がGitLabに連携されれば設定完了です。

6. Jenkinsのジョブに成功したMerge Requestだけマージできるようにする

Gitlabの対象レポジトリのSettingsMerge request settingsExpandを押し、Only allow merge requests to be merged if the pipeline succeedsにチェックを入れます。

その他

ローカルネットワークで疎通する場合はGitLabのAdmin SettingsOutbound RequestAllow requests to the local networkにチェックを入れる必要があるケースがあります。

参考情報

Mattermostも連携する手順はJenkinsとGitLabとMattermostを連携する方法をご覧ください。