Jenkins との連携

Jenkins for Jira は、ファイアウォールの内側で実行されている Jenkins サーバーと、Jira Software Cloud または Jira Service Management Cloud のいずれかを接続するための、安全で信頼できる無料の手段を提供します。

これによって、チームは Jira のすべての課題の詳細ビューで可視性とコンテキストを活用して、最新のビルド ステータスや、その作業が環境に正常にデプロイされたかどうかを確認できるようになります。

また、この情報によって Jira クエリ言語 (JQL) で複数の課題全体を検索して現在のスプリントのどの課題が本番環境にデプロイされたか」などの質問に回答できるようになります。これらをボード上にクイック フィルターとして追加するさえもできます。

はじめる前に

Jenkins for Jira を接続して Jira プロジェクトにデータを流すには、次のタスクを実行または委任する必要があります。

  1. Jira で Jenkins for Jira アプリをインストールする

  2. Jira で Jenkins への接続を開始する

  3. Jenkins で Atlassian Jira Software Cloud プラグインをインストールする (必要な場合)

  4. Jenkins で、Jira に用意されている接続認証情報を入力して接続を完了する

  5. ソース コード管理プラットフォームか Jenkins で、プロジェクトの Jenkinsfiles を編集して Jenkins から Jira に送信されるデータを設定する

多くのチームでは、これらのタスクを適切な権限と経験を持つチーム メンバーに分けるのが理にかなっています。

Jenkins for Jira の接続プロセスを参考にして、これらのタスクを委任してください。ただし、始める前に、Jenkins 管理者が誰で、どのチーム メンバーが Jenkins パイプラインを定義する Jenkinsfiles の編集を担当しているかを知っておく必要があります。

これらのチーム メンバーが誰なのかわからない場合は、Jenkins を使用してコードをビルドおよびデプロイしている Jira プロジェクト チームに連絡してください。Jira プロジェクト チームが該当する担当者を教えてくれます。

Jira Cloud サイトに Jenkins for Jira をインストールする

必要な権限: Jira サイト管理者

Jenkins for Jira (公式) アプリを Atlassian Marketplace からインストールします。

  1. Jira サイトにログインして [アプリ] > [その他のアプリを探す] の順に移動します。

  2. Jenkins for Jira (公式) アプリを検索して、[アプリを入手] を選択します。

Jira で Jenkins への接続を開始する

必要な権限: Jira サイト管理者

Jenkins for Jira アプリを Jira サイトにインストールしたら、Jenkins への接続を開始する必要があります。

  1. Jira で [アプリ] > [アプリを管理] の順に移動します。

  2. 左側のサイドバーの [アプリ] の下で、[Jenkins for Jira] を選択します。

  3. これが初めての接続である場合は、接続ウィザードが表示されます。以前に Jenkins サーバーに接続したことがある場合は、[Connect another server (別のサーバーに接続)] を選択してウィザードに進みます。

接続ウィザードの画面に表示される指示に従います。Jenkins 管理者である場合と Jenkins 管理者のサポートを受けている場合でここでの操作は異なりますが、いずれの場合も、サーバーに名前を付けると、2 つの認証項目 (Webhook URL と Jenkins で使用するシークレット トークン) が表示されます。

接続プロセスを完了するには、あなたまたは Jenkins 管理者が Jenkins にログインし、サーバーをセットアップし、これらの認証情報を使用して接続を完了する必要があります。

Jenkins サーバーに Atlassian Jira Software Cloud プラグインをインストールする

必要な権限: Jenkins 管理者

Jira サイト管理者が Jira で接続を開始したら、Jira Cloud プラグインを Jenkins にインストールして接続を完了する必要があります。

  1. Jenkins サーバーにログインして、[Jenkins の管理] > [Plugins (プラグイン)] > [Available plugins (利用可能なプラグイン)] の順に移動します。

  2. アトラシアン Jira Software Cloud を検索して、プラグインをインストールします。

[Available plugins (利用可能なプラグイン)] 画面でプラグインが見つからない場合は、すでにサーバーにインストールされている可能性があります。確認方法は次の通りです。

  1. Jenkins サーバーにログインして、[Jenkinsの管理] > [Plugins (プラグイン)] > [インストール済みプラグイン] の順に移動します。

  2. アトラシアン Jira Software Cloud を検索します。

  3. プラグインがすでにインストールされている場合は、利用可能なアップデートを実行します。

Jenkins サーバーで接続を完了する

必要な権限: Jenkins 管理者

Jenkins サーバーにアトラシアン Jira Software Cloud プラグインがインストールされ、Webhook URL とシークレット トークンが手元にあれば、Jenkins と Jira 間の接続を完了させることができます。

  1. Jenkins で、[Jenkins の管理] > [Atlassian Jira Software Cloud (アトラシアン Jira Software Cloud)] の順に移動します。

  2. [Add new site (新しいサイトを追加)] を選択します。

  3. Jira サイト名を入力します。

  4. Webhook URL を入力します。

  5. Jenkins の認証情報マネージャーを使用してシークレットを入力します。

    1. [追加] を選択します。

    2. [Kind (種類)] ドロップダウンから、[Secret text (シークレットのテキスト)] を選択します。

    3. Jenkins for Jira 接続ウィザードで指定されたシークレットを [シークレット] フィールドに貼り付けます。

    4. シークレットの分かりやすい名前 (サイト名など) を [説明] フィールドに指定します。

    5. [追加] を選択します。

    6. [シークレット] ドロップダウンを使用して、先ほど入力したシークレットを選択します。

  6. [Test connection] を選択して、Jira サイトで認証情報が有効であることを確認します。

  7. [保存] を選択します。

  8. サイト名と認証情報を正常に入力すると、[Jenkins の管理] > [Atlassian Jira Software Cloud (アトラシアン Jira Software Cloud)] に戻ります。

  9. (省略可) チームで必要な場合はビルドとデプロイの自動化を設定します。

  10. [保存] を選択します。

この時点で Jenkins サーバーが Jira に接続されます。

Jenkins 管理者として接続プロセスを完了させるために Jira サイト管理者をサポートしている場合は、接続が完了したことを Jira サイト管理者に知らせます。Jenkins 権限を持つ Jira サイト管理者 (つまり、セットアップをすべて自分で完了する場合) の場合は、このタイミングで Jira に戻ります。

Jenkinsfile を編集して Jenkins サーバーから Jira サイトへのデータフローを設定する

必要な権限: Jenkins サーバーまたはソース コード管理プラットフォーム上の Jenkinsfile への書き込みアクセス権限

Jenkins サーバーが Jira に接続されると、サーバーから Jira に流れるデータをチームで選択するうえで役立つセット アップ ガイドが Jira によって生成されます。Jenkins からビルドとデプロイのイベントを受信するには、チームでこのガイドに従う必要があります。

サーバーのセット アップ ガイドにアクセスする方法は以下のとおりです。

  1. Jira で [アプリ] > [アプリを管理] の順に移動します。

  2. 左側のサイドバーの [アプリ] の下で、[Jenkins for Jira] を選択します。

  3. 先ほど選択したサーバーに移動し、[Set up guid (セットアップ ガイド)] タブを開きます。このガイドでは、Jenkins と Jira の間のデータの流れを設定するためにチームですべきことが説明されています。

  4. ほとんどの場合、セット アップ ガイドの情報はプロジェクト チームの開発者が最もよく使用します。[Share this guide with your team (このガイドをチームと共有)] を使用し、Jenkins 管理ページの読み取り専用バージョンのガイドをチームに送信します。

  5. Jenkins サーバーから Jira に送信するビルド イベントをチームで設定すると、それらのイベントがサーバーの [Recent events (最近のイベント)] タブに表示されるようになります。

Jenkins for Jira の仕組み

この参照ガイドを使用して、Jenkins for Jira の仕組みを理解したり、セットアップ ガイドに従わずにデータ フローを設定したりできます。

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 (アトラシアン Jira Software Cloud)] の順に移動します。

  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 (アトラシアン Jira Software Cloud)] の順に移動します。

  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 プロジェクトに接続する方法をご確認ください。

詳細

その他のヘルプ