Edited at

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を連携する方法をご覧ください。