Jenkins

13.7でGitLab Freeに移行しました。

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

GitLab の Jenkins インテグレーションの概要については、Jira イシューと Jenkins パイプラインによる GitLab ワークフローをご覧ください。

以下の場合に Jenkins インテグレーションを使用してください：

  • 将来的にCIをJenkinsからGitLab CI/CDにマイグレーションする予定があり、暫定的なソリューションが必要な場合。
  • Jenkinsプラグインに投資しており、アプリのビルドにJenkinsを使い続けることを選択している場合。
note
このドキュメントは、JenkinsとGitLabのインテグレーションを設定する方法のみに焦点を当てています。開発者向けドキュメントではローカルマシン上でJenkins をセットアップする方法を、Jenkins からの移行ドキュメントでは Jenkins から GitLab CI/CD にマイグレーションする方法を学んでください。

JenkinsインテグレーションはGitLabとJenkinsの両方で設定が必要です。

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

JenkinsにGitLabプロジェクトへのアクセス権を付与します：

  1. 個人、プロジェクト、グループのアクセストークンを作成します。

    • 個人アクセストークンを作成すると、そのユーザーのすべてのJenkinsインテグレーションでトークンが使用されます。
    • プロジェクト・アクセストークンを作成すると、トークンをプロジェクト・レベルでのみ使用できます。インスタンスンスでは、他のプロジェクトのJenkinsインテグレーションに影響を与えることなく、プロジェクトのトークンを取り消すことができます。
    • グループアクセストークンを作成すると、そのグループのすべてのプロジェクトのすべてのJenkinsインテグレーションでトークンを使用できます。
  2. アクセストークンのスコープをAPIに設定します。
  3. アクセストークンの値をコピーして、Jenkinsサーバーを設定します。

Jenkinsサーバーの設定

Jenkinsプラグインをインストールして設定します。プラグインをインストールし、GitLabへの接続を承認するように設定する必要があります。

  1. Jenkins サーバーで、Manage Jenkins > Manage Plugins を選択します。
  2. JenkinsのGitLabプラグインをインストールします。
  3. Manage Jenkins > Configure Systemを選択します。
  4. GitLabセクションで、Enable authentication for ‘/project’エンドポイントを選択します。
  5. Add を選択し、Jenkins Credential Provider を選択します。
  6. トークンの種類としてGitLab API tokenを選択します。
  7. API Tokenに GitLabからコピーした値を貼り付け、Addを選択します。
  8. GitLab host URLにGitLabサーバーのURLを入力します。

  9. 接続をテストするには、Test Connectionを選択します。

    Jenkins plugin configuration

詳細については、Jenkins-to-GitLab 認証を参照してください。

Jenkinsプロジェクトの設定

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

  1. Jenkinsインスタンスで、New Itemに進みます。
  2. プロジェクト名を入力します。
  3. FreestyleまたはPipelineを選択し、OK を選択します。JenkinsプラグインがGitLab上のビルドステータスを更新するので、Freestyleプロジェクトをお勧めします。パイプラインプロジェクトでは、GitLab 上のステータスを更新するスクリプトを設定する必要があります。
  4. ドロップダウンリストから GitLab 接続を選択します。
  5. 変更がGitLabにプッシュされたときにビルドを選択します。
  6. 以下のチェックボックスを選択します：
    • 受け付けられたマージリクエストイベント
    • 終了したマージリクエストイベント
  7. ビルドステータスが GitLab にどのようにレポートされるかを指定します：
    • Freestyleプロジェクトを作成した場合、Post-build Actionsセクションで、Publish build status to GitLab を選択します。

    • パイプラインプロジェクトを作成した場合は、Jenkinsパイプラインスクリプトを使用してGitLabのステータスを更新する必要があります。

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

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

      その他のJenkinsパイプラインスクリプトの例については、GitHubのJenkins GitLabプラグインリポジトリを参照してください。

GitLabプロジェクトの設定

以下のいずれかの方法で、GitLabとJenkinsのインテグレーションを設定します。

GitLab では、Jenkins インテグレーションの設定がWebhook インテグレーションよりも簡単なので、この方法を推奨しています。

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定]>[インテグレーション]を選択します。
  3. Jenkinsを選択します。
  4. アクティブ]チェックボックスを選択します。
  5. GitLabにJenkinsビルドをトリガーさせたいイベントを選択します：
    • プッシュ
    • マージリクエスト
    • タグプッシュ
  6. JenkinsサーバーのURLを入力します。
  7. オプション。SSL検証を無効にするには、[SSL検証を有効にする]チェックボックスをオフにします。

  8. プロジェクト名を入力します。

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

  9. Jenkinsサーバーで認証が必要な場合は、ユーザー名と パスワードを入力します。
  10. オプション。Test settingsを選択します。
  11. 変更を保存を選択します。

Webhookの設定

Jenkinsサーバーのログイン情報をGitLabに提供できない場合、このオプションを使ってGitLabとJenkinsをインテグレーションすることができます。

  1. Jenkinsジョブの設定で、GitLabの設定セクションでAdvancedを選択します。
  2. シークレットトークン]で[生成]を選択します。
  3. トークンをコピーし、ジョブ設定を保存します。
  4. GitLab でプロジェクトの Webhook を作成し、トリガーの URL (https://JENKINS_URL/project/YOUR_JOB など) を入力してSecret Tokenにトークンを貼り付けます。
  5. Webhook をテストするには、Test を選択します。

トラブルシューティング

GitLab設定中のエラー - “接続に失敗しました。設定を確認してください”

GitLabの設定中にこのエラーメッセージが表示された場合、以下の原因が考えられます：

  • GitLabがアドレスにあるJenkinsインスタンスに到達できません。GitLabインスタンスが自己管理されている場合、GitLabインスタンスで提供されたドメインでJenkinsインスタンスにpingを打ってみてください。
  • Jenkinsインスタンスはローカルアドレスにあり、GitLabインストールの許可リストに含まれていません。
  • Jenkinsインスタンスの認証情報が十分なアクセス権を持っていないか、無効です。
  • Jenkins プラグインの設定で、Enable authentication for/project end-point チェックボックスが選択されていません。

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

GitLabがJenkinsからCommit Status API経由でビルドステータスの更新を受け取らなかった場合、Could not connect to the CI server のエラーが表示されるかもしれません。

このイシューはJenkinsが適切に設定されていないか、API経由でステータスを報告するエラーがある場合に発生します。

このイシューを修正するには、以下を確認してください：

  1. GitLab APIアクセス用にJenkinsサーバーを設定します。
  2. Jenkinsプロジェクトの設定。’Publish build status to GitLab’ post-buildアクションを含みます。

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

このイシューは、リクエストがWebhook のタイムアウト（デフォルトでは 10 秒に設定）を超過した場合に発生する可能性があります。

このイシューについては、以下を確認してください：

  • インテグレーション Webhook ログにリクエストの失敗がないか確認してください。

  • /var/log/gitlab/gitlab-rails/production.log のようなメッセージに対して

     WebHook Error => Net::ReadTimeout

    あるいは

     WebHook Error => execution expired

セルフマネジメントの GitLab インスタンスでは、Webhook のタイムアウト値を大きくすることでこのイシューを解決できます。

Jenkinsでジョブログを有効にする

インテグレーションに関する問題をトラブルシューティングするために、Jenkinsでジョブログを有効にして、ビルドに関する詳細を取得することができます。

Jenkinsでジョブログを有効にするには：

  1. ダッシュボード > Jenkinsの管理 > システムログに移動します。
  2. Add new log recorderを選択します。
  3. ログレコーダの名前を入力します。
  4. 次の画面で、「Add」を選択し、「com.dabsquared.gitlabjenkins 」と入力します。
  5. ログレベル］が［すべて］であることを確認し、［保存］を選択します。

ログを表示するには

  1. ビルドを実行します。
  2. ダッシュボード > Jenkinsの管理 > システムログに移動します。
  3. ロガーを選択し、ログを確認します。