Jenkins for Jira の仕組み

この記事は、Jenkins for Jira アプリの仕組みを説明するリファレンス ガイドです。Jira チームによるサイトと Jenkins サーバー間の接続設定を手伝う Jenkins 管理者の参考になる場合があります。

ほとんどの場合、この技術的な詳細情報は Jira Software Cloud の管理者やプロジェクト チームには必要ありません。管理者やプロジェクト チームの方は、Jenkins for Jira アプリのガイド付きの接続プロセスや「Jenkins と連携する」の記事に従ってください。

Jenkins が Jira にデータを送信する方法

パイプラインが Jenkins で実行されるたびに、アトラシアン Jira Software Cloud プラグインは、そのパイプラインについて説明する Jenkinsfile を調べて、Jiraにデータを送信すべきサインがないか確認します。

プラグインは次の 2 つを検索します。

  1. ビルドまたはデプロイの各ステージにおける特定の指示 (jiraSendBuildInfojiraSendDeploymentInfo)。

  2. ビルドとデプロイの各ステージでの特定の命名規則 (プラグインが特定の命名規則を検索するように設定されている場合)

プラグインがこれらのいずれかを見つけたら、コミット メッセージ内の Jira 課題キーと、そのステージでビルドまたはデプロイされているコードのブランチ名をそれぞれ検索します。これらが見つかると、ステージに関するイベント データ (ビルドが成功したか失敗したかなど) を Jira に送信します。課題キーが見つからない場合、プラグインは Jira にデータを送信しません。

Jira が Jenkins からデータを受信する方法

Jira が Jenkins からイベント データを受け取ると、Jenkins for Jira アプリは関連するイベント データを Jira 課題、デプロイ パイプライン、およびリリース機能に表示します。アプリは、サイトに関連する課題キーを含まないイベントをすべて破棄します。

必要なアクション

Jenkins からビルド データとデプロイ データを受け取るには、次の点に留意してください。

  • サーバーのパイプラインについて説明する Jenkinsfile には、アトラシアン Jira Software Cloud プラグインが Jira にデータを送信するタイミングが示されている必要があります

  • チームは Jira 課題キー (例: FUSE-123) をコミット メッセージとブランチ名に含める必要があります。そうすることで、Jenkins からのイベント データがサイトに関連していることを Jenkins for Jira が認識できます

Jira にデータを送信するように Jenkinsfile を設定する方法は次のとおりです。

ステージ名を使ってビルド データを Jira に送信する

Jenkinsfile に特定の指示を追加せずにビルド イベントを送信するには、次の手順を実行します。

  1. [Jenkins の管理] > [Atlassian Jira Software Cloud] > [Advanced settings (optional) (詳細設定 (オプション))] の順に移動します。

  2. [ビルドを自動送信] チェックボックスをオンにします。

これを有効にすると、パイプラインの実行が開始されると「進行中」の、パイプラインが正常に終了すると「成功」の、エラーにより停止すると「失敗」の各ビルド イベントが、プラグインから Jira に送信されます。

ビルドに正規表現も指定した場合、プラグインは一致する名前を持つビルド ステップが完了した後にのみ Jira にビルド イベントを送信します。

正規表現 ^build$ は、次の Jenkinsfilebuild ステージに一致します。次に例を示します。

1 2 3 4 5 6 7 8 9 10 pipeline { agent any stages { stage('build') { steps { echo 'build done' } } } }

この Jenkinsfile 内のパイプラインが実行されるたびに、build ステージの開始時と終了時に、ビルド イベントをすべての設定済み Jira Cloud サイトに送信します。

ステージ名を使ってデプロイ データを Jira に送信する

Jenkinsfile に特定の指示を追加せずにビルド イベントを送信するには、次の手順を実行します。

  1. [Jenkins の管理] > [Atlassian Jira Software Cloud] > [Advanced settings (optional) (詳細設定 (オプション))] の順に移動します。

  2. [デプロイを自動送信する] チェックボックスをオンにします。

これを有効にすると、指定した正規表現と一致する名前のビルド ステップの実行が開始されると「進行中」の、ビルド ステップが終了すると「成功」または「失敗」の各ビルド イベントが、プラグインからJira に送信されます。

これを機能させるには、Jenkinsfile 内のデプロイ ステップの名前に環境名が含まれている必要があります。正規表現にはフラグメント ((?<envName>.*)) を含めて環境名と一致させ、プラグインがビルド ステップ名から環境名を抽出できるようにします。

Jenkinsfile の例を以下に示します。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 pipeline { agent any stages { stage('deployments') { parallel { stage('deploy to stg') { steps { echo 'stg deployment done' } } stage('deploy to prod') { steps { echo 'prod deployment done' } } } } } }

 [デプロイを自動送信する] チェックボックスがオンで正規表現が ^deploy to (?<envName>.*)$ に設定されている場合は、上記の Jenkinsfile を実行すると、stgprod の各環境の「進行中」デプロイ イベントがすべての設定済み Jira Cloud サイトに送信されます。その後、ビルド ステップが完了するとそれぞれの「成功」デプロイ イベントが送信されます。

明示的な指示を使ってビルド データを Jira に送信する

ビルド イベントを送信するタイミングをより細かく制御する場合は、jiraSendBuildInfo ビルド ステップを使用できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 pipeline { agent any stages { stage('Build') { steps { echo 'Building...' } post { always { // previous to version 2.0.0 you must provide parameters to this command (see below)! jiraSendBuildInfo() } } } } }

これによって、Build ステージが正常に完了すると「成功」、エラーが発生すると「失敗」ビルド イベントが、すべての設定済み Jira Cloud サイトに送信されます。Jenkins プラグインはブランチ名から Jira 課題キーを自動抽出します。

また、Jira サイトの URL を指定して、ビルド イベントを (すべての設定済み Jira サイトではなく) この Jira サイトにのみ送信するようにプラグインに指示できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 pipeline { agent any stages { stage('Build') { steps { echo 'Building...' } post { always { jiraSendBuildInfo site: 'example.atlassian.net', branch: 'TEST-123-awesome-feature' } } } } }

明示的な指示を使ってデプロイ データを Jira に送信する

デプロイ イベントを送信するタイミングをより細かく制御する場合は、jiraSendDeploymentInfo ビルド ステップを使用できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 pipeline { agent any stages { stage('Deploy - Staging') { when { branch 'master' } steps { echo 'Deploying to Staging from master...' } post { always { jiraSendDeploymentInfo environmentId: 'us-stg-1', environmentName: 'us-stg-1', environmentType: 'staging' } } } stage('Deploy - Production') { when { branch 'master' } steps { echo 'Deploying to Production from master...' } post { always { jiraSendDeploymentInfo environmentId: 'us-prod-1', environmentName: 'us-prod-1', environmentType: 'production' } } } }

これによって、Deploy - StagingDeploy - Productionの各ステージの終了時に、すべての設定済み Jira サイトに「成功」または「失敗」の各デプロイ イベントが送信されます。

パラメーター environmentIdenvironmentNameenvironmentType を指定する必要がありますenvironmentType は、unmappeddevelopmenttestingstagingproduction のいずれかである必要があります。

デプロイ イベントを、すべての設定済み Jira サイトではなく単一の Jira サイトに送信するように、パラメーター siteを指定できます。

複数の Jira サイトが Jenkins サーバーに接続されている場合は、enableGating:true を指定した jiraSendDeploymentInfosite パラメーターに必要です。デプロイ ゲートの詳細についてはこちらをご参照ください。

また、branch パラメーターによってブランチを指定して、デプロイを接続する Jira 課題キーを抽出するブランチを定義できます。

完全な Jenkinsfile の例

以下の Jenkinsfile のように、ビルドとデプロイを組み合わせられます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 pipeline { agent any stages { stage('Build') { steps { echo 'Building...' } post { always { jiraSendBuildInfo site: 'example.atlassian.net' } } } stage('Deploy - Staging') { when { branch 'master' } steps { echo 'Deploying to Staging from master...' } post { always { jiraSendDeploymentInfo environmentId: 'us-stg-1', environmentName: 'us-stg-1', environmentType: 'staging' } } } stage('Deploy - Production') { when { branch 'master' } steps { echo 'Deploying to Production from master...' } post { always { jiraSendDeploymentInfo environmentId: 'us-prod-1', environmentName: 'us-prod-1', environmentType: 'production' } } } } }

Jira で開発情報を表示する

Bitbucket や GitHub などの接続されたソース コード管理ツールでプル リクエストをコミットまたはマージするたびに、そのリポジトリに指定した Jenkins パイプラインが実行されます。チームが課題キーをプル リクエスト、コミット メッセージ、ブランチ名に含めていれば、Jira 課題の開発パネルが更新されて関連するビルドとデプロイの情報が表示されます。課題の開発情報を表示する方法に関する詳細についてご確認ください。

Jira で開発情報を表示する

デプロイ機能を Jira プロジェクトで有効にしている場合、デプロイ ページではすべての Jenkins デプロイをタイムラインに表示します。環境、担当者、課題タイプなどでデプロイをフィルタリングまたは検索して表示できます。また、チームがリリースとバージョンによって作業を整理している場合は、リリース機能にもデプロイ情報が表示されます。

Jenkins を Jira Service Management Cloud プロジェクトに接続する方法をご確認ください。

詳細

さらにヘルプが必要ですか?

アトラシアン コミュニティをご利用ください。