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 つを検索します。

ビルドまたはデプロイの各ステージにおける特定の指示 (jiraSendBuildInfo と jiraSendDeploymentInfo)。
ビルドとデプロイの各ステージでの特定の命名規則 (プラグインが特定の命名規則を検索するように設定されている場合)

プラグインがこれらのいずれかを見つけたら、コミットメッセージ内の 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 に特定の指示を追加せずにビルドイベントを送信するには、次の手順を実行します。

[Jenkins の管理] > [Atlassian Jira Software Cloud] > [Advanced settings (optional) (詳細設定 (オプション))] の順に移動します。
[ビルドを自動送信] チェックボックスをオンにします。

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

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

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

pipeline {
    agent  any
    stages {
        stage('build') {
            steps {
                echo  'build done'
            }
        }
    }
}

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

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

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

[Jenkins の管理] > [Atlassian Jira Software Cloud] > [Advanced settings (optional) (詳細設定 (オプション))] の順に移動します。
[デプロイを自動送信する] チェックボックスをオンにします。

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

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

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

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 を実行すると、stg と prod の各環境の「進行中」デプロイイベントがすべての設定済み Jira Cloud サイトに送信されます。その後、ビルドステップが完了するとそれぞれの「成功」デプロイイベントが送信されます。

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

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

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 サイトにのみ送信するようにプラグインに指示できます。

pipeline {
     agent any
     stages {
         stage('Build') {
             steps {
                 echo 'Building...'
             }
             post {
                 always {
                     jiraSendBuildInfo site: 'example.atlassian.net', branch: 'TEST-123-awesome-feature'
                 }
             }
         }
     }
 }

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

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

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 - StagingとDeploy - Productionの各ステージの終了時に、すべての設定済み Jira サイトに「成功」または「失敗」の各デプロイイベントが送信されます。

パラメーター environmentId、environmentName、environmentType を指定する必要があります。environmentType は、unmapped、development、testing、staging、production のいずれかである必要があります。

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

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

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

完全な Jenkinsfile の例

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

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

Jira Service Management Cloud を Jenkins とリンクする

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

詳細

Jira Software Cloud と他のオンプレミスツールの間で独自の連携を作成する

この内容はお役に立ちましたか?

正確ではなかった

明確ではなかった

関係なかった

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

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

コミュニティに質問