Jenkins CIサービス

注:このドキュメントはJenkinsとGitLabのインテグレーションを 設定する方法のみに焦点を当てています。 JenkinsからGitLab CI/CDに移行する方法については、Jenkinsからの移行ドキュメントをご覧ください。

GitLab から、リポジトリにコードをプッシュしたときやマージリクエストが作成されたときに Jenkins のビルドをトリガーすることができます。 その見返りとして、Jenkins はマージリクエストウィジェットや GitLab プロジェクトのホームページにパイプラインのステータスを表示します。

GitLabのJenkinsインテグレーションをより理解するために、以下のビデオをご覧ください:

実際の使用例については、ブログポスト「Continuous integration: From Jenkins to GitLab usingdocker」をお読みください。

従来のCIプラグインから、ソフトウェア開発ライフサイクル全体をカバーする単一のアプリケーションに移行することで、ツールチェーンのメンテナーに費やす時間を10%以上削減することができます。 詳細については、GitLabvs. Jenkins」の比較ページをご覧ください。

GitLabとJenkinsのインテグレーション設定

GitLabのJenkinsインテグレーションには、GitLabとJenkinsの両方にインストールと設定が必要です。 GitLabでは、Jenkinsに関連プロジェクトへのアクセス権を与える必要があります。 Jenkinsでは、いくつかのプラグインをインストールして設定する必要があります。

GitLabの要件

ジェンキンス要件

GitLabプロジェクトにJenkinsのアクセスを許可します。

GitLabユーザーに選択したGitLabプロジェクトへのアクセスを許可します。

  1. 新しいGitLabユーザーを作成するか、既存のGitLabユーザーを選択します。

    このアカウントは、JenkinsがGitLabプロジェクトにアクセスするために使用されます。 この目的のためだけにGitLabユーザーを作成することをお勧めします。 もしあなたがある人のアカウントを使用し、そのアカウントが無効化されたり削除されたりすると、GitLabとJenkinsのインテグレーションは機能しなくなります。

  2. GitLab プロジェクトへの権限を付与します。

    Jenkinsを多くのGitLabプロジェクトとインテグレーションする場合は、ユーザーにグローバルな管理者権限を与えることを検討してください。 そうでない場合は、プロジェクトごとにユーザーを追加し、開発者権限を与えてください。

GitLab API アクセスの設定

JenkinsのGitLabへのアクセスを認可するための個人アクセストークンを作成します。

  1. Jenkinsで使用するユーザーとしてGitLabにログインします。
  2. アバターをクリックし、次に**設定をクリックします。
  3. サイドバーの「アクセストークン」をクリックします。
  4. APIスコープのチェックボックスをオンにして、パーソナルアクセストークンを作成します。 詳細は、パーソナルアクセストークンを参照してください。
  5. 個人アクセストークンの値は、Jenkinsサーバーの構成で必要なため、記録してください。

Jenkinsサーバーの設定

Jenkinsプラグインのインストールと設定 GitLabへの接続を作成するためには、両方のプラグインをインストールし、設定する必要があります。

  1. Jenkinsサーバーで、Manage Jenkins > Manage Pluginsに進みます。
  2. JenkinsのGitLabプラグインをインストールします。
  3. Manage Jenkins > ConfigureSystemに進みます。
  4. GitLabセクションで、Enable authentication for ‘/project’ end-pointチェックボックスをオンにします。
  5. Addをクリックし、Jenkins Credential Providerを選択します。
  6. トークンの種類としてGitLab API トークンを選択します。
  7. API TokenフィールドにGitLabパーソナルアクセストークンの値を入力し、Addをクリックします。
  8. GitLabhost URLフィールドにGitLabサーバーのURLを入力します。
  9. 接続のテスト]をクリックし、接続が成功したことを確認してから次に進みます。

詳細については、Jenkins-to-GitLab 認証に関するGitLab Plugin のドキュメントを参照してください。

Jenkins GitLab plugin configuration

Jenkinsプロジェクトの設定

ビルドを実行するJenkinsプロジェクトを設定します。

  1. ジェンキンス・インスタンスで、「New Item」に進みます。
  2. プロジェクト名を入力してください。
  3. JenkinsプラグインがGitLab上のビルドステータスを更新するので、Freestyleプロジェクトをお勧めします。 Pipelineプロジェクトでは、GitLab上のステータスを更新するスクリプトを設定する必要があります。
  4. ドロップダウンからGitLab接続を選択します。
  5. Build when a change is pushed toGitLab チェックボックスをチェックします。
  6. 以下のチェックボックスにチェックを入れてください:
    • 承認されたマージリクエストイベント
    • 非公開マージリクエストイベント
  7. GitLabへのビルドステータスの報告方法を指定します:
    • Freestyleプロジェクトを作成した場合は、Post-build Actionsセクションで、Publish build status toGitLabを選択します。
    • パイプラインプロジェクトを作成した場合は、Jenkinsパイプラインスクリプトを使ってGitLabのステータスを更新する必要があります。

      Jenkinsパイプラインスクリプトの例:

       pipeline {
          agent any
      
          stages {
             stage('gitlab') {
                steps {
                   echo 'Notify GitLab'
                   updateGitlabCommitStatus name: 'build', state: 'pending'
                   updateGitlabCommitStatus name: 'build', state: 'success'
                }
             }
          }
       }
      

GitLabプロジェクトの設定

GitLabとJenkinsのインテグレーションを設定します。

  1. 新しいGitLabプロジェクトを作成するか、既存のプロジェクトを選択します。
  2. 設定 >インテグレーションに移動し、Jenkins CIを選択します。
  3. アクティブトグルをオンにします。
  4. GitLabにJenkinsビルドをトリガーさせたいイベントを選択します:
    • プッシュ
    • マージリクエスト
    • タグプッシュ
  5. JenkinsのURLを入力してください。
  6. プロジェクト名を入力してください。

    プロジェクト名は、スペースがアンダースコアに置き換えられるURLフレンドリーでなければなりません。 プロジェクト名が有効であることを確認するには、Jenkinsプロジェクトを表示しているときにブラウザのアドレスバーからコピーします。

  7. Jenkinsサーバーで認証が必要な場合は、ユーザー名と パスワードを入力します。
  8. Test settingsをクリックし、変更を保存します。 GitLabはJenkinsへの接続をテストします。

プラグイン機能概要

GitLabにはコミットを一覧するデータベーステーブルがありません。 コミットは常にリポジトリから直接読み込まれます。 そのため、GitLabでコミットのビルドステータスを保持することはできません。 これは、統合されたCIツールにビルド情報をリクエストすることで克服されます。 CIツールは、コミットとマージリクエストのビルドステータスを作成し、保存する責任を負います。

同様のインテグレーションを実施するために必要なステップ

注:すべてのステップはマージリクエストページでAJAXリクエストを使用して実装されます。

  1. マージリクエストでビルドステータスを表示するには、GitLabでプロジェクトサービスを作成する必要があります。
  2. プロジェクトサービスは、コミットの SHA1 を CI ツールの URL に(JSON) クエリします。
  3. プロジェクトサービスは、プロジェクトサービスの設定とCIツールの知識に基づいて、このURLとペイロードを構築します。
  4. レスポンスはGitLabのレスポンス(成功/失敗/保留)として解析されます。

トラブルシューティング

マージリクエストのエラー - “CIサーバーに接続できませんでした”

このインテグレーションは、JenkinsがCommit Status APIを通じてGitLabにビルドステータスを報告することに依存しています。

Could not connect to CI server’というエラーは通常、GitLabがAPI経由でビルドステータスの更新を受け取らなかったことを意味します。 Jenkinsが適切に設定されていないか、API経由でステータスをレポーターするエラーが発生したかのどちらかです。

  1. GitLab APIにアクセスするためのJenkinsサーバーの設定
  2. ビルド後のアクション ‘Publish build status to GitLab’ を含め、Jenkinsプロジェクトを設定します。

マージリクエストイベントがJenkinsパイプラインをトリガーしません。

サービスフックのログでリクエストの失敗をチェックするか、/var/log/gitlab/gitlab-rails/production.log ファイルで以下のようなメッセージをチェックしてください:

WebHook Error => Net::ReadTimeout

あるいは

WebHook Error => execution expired

これらが存在する場合、リクエストは webhook のタイムアウトを超過しています(デフォルトでは 10 秒に設定されています)。

この問題を解決するには、gitlab.rb の設定ファイルでgitlab_rails['webhook_timeout'] の値を増やし、gitlab-ctl reconfigure のコマンドを実行する必要があります。

上記のエラーは見つからないが、以下のような重複したエントリが見つかった場合(/var/log/gitlab/gitlab-rail)、webhookリクエストがタイムアウトしている可能性があります:

2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start
2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start