ワークフローのトリガー設定
このページは、トリガーの使用を開始するのに役立ちます。ワークフローのトリガーを設定する方法と、自動遷移を動作させる方法を示します。トリガーのベストな設定方法と、トリガーのトラブルシューティングに役立ついくつかのガイダンスを提供しています。
はじめる前に
Before you can start using triggers, you need to connect your development tools to Jira Software. At a minimum, you will need a Jira Data Center instance, plus at least one of the following:
- Bitbucket Data Center(すべての最新バージョン)
- FishEye/Crucible (すべての 最新バージョン)
- GitHub Enterprise 11.10.290 (以上)
- Bitbucket
- GitHub
これらのツールを Jira に接続する方法の手順については、「開発ツールを統合する」を参照してください。このページには、Atlassian の提供する様々な開発ツールを接続することで有効になるその他の機能の詳細も含まれています。
ガイド: トリガーのセットアップ
この例では、トリガーを持つ Jira ワークフローを設定します。このセクションを終了すると、トリガーの設定方法と、トリガーを持つ一般的な開発ワークフローがどのように見えるか理解することができます。
はじめに
The screenshot and table below show a workflow and triggers similar to what you will be configuring. They reflect the typical interactions between Jira and development tools in a software development lifecycle. Jira Software , Bitbucket Data Center and Fisheye/Crucible (3.5.2) are used for this example, but you can configure something similar using any of the supported development tools.
トランジション | トリガー |
---|---|
Start progress | ブランチを作成(Bitbucket Data Center) |
Start review | プル リクエストを作成(Bitbucket Data Center) |
Restart progress | プル リクエストを却下(Bitbucket Data Center) |
Done | プル リクエストをマージ(Bitbucket Data Center) |
ステップ 1.ワークフローを作成/編集する
ソフトウェア開発ワークフローを作成する最も簡単な方法は、新しいプロジェクトの作成で関連するプロジェクト タイプを選択することです。これにより、上記で示したものと同一のソフトウェア開発ワークフローを持つ新しいプロジェクトをセットアップします。
既に同様のワークフローがある場合、それを操作、編集します: Jira 管理コンソール > 課題 > ワークフロー > 編集
ステップ 2.トランジションにトリガーを追加する
「コミットの作成」トリガーを「開始」トランジションに追加することで始めます。ワークフローを編集(表示ではなく)していることを確認します。
1. ワークフローの Start progress トランジション、すなわち "To Do" から "In Progress" への線を選択します。右側にパネルが表示され、トランジションの詳細が表示されます。
関連トピック: グローバル トランジションでトリガーを設定すべきではない理由
2. パネルの [トリガー] をクリックします。[トリガー] タブを持つ [トランジション: Start Progress] 画面が表示されます。
3. [トリガーの追加] をクリックし、表示されるダイアログで [コミットの作成] を選択します。診断画面が表示されます。Jira に接続されているすべての開発ツールのトリガーが追加されていることがわかります。
関連トピック: トリガーに異なるイベントを有効化する方法
4. [トリガーの追加] をクリックしてトリガーを追加します。[トリガー] タブの一番下のリストに表示されます。[詳細の表示] をクリックして動作しているかどうかを確認することができます。
これで完了です。ワークフローの下書きを公開することを忘れないで下さい。
ステップ 3.トリガーをテストする
これで「開始」トランジションに「コミットの作成」トリガーを追加したので、コミットしてテストしてみます。
1. Jira プロジェクトで課題を作成します。このプロジェクトでは、編集したワークフローを使用する必要があります。
新しい課題のステータスは「作業前」である必要があります。次のステップで必要になるので、課題のキーをメモしておいてください。
2. 一部のコードを Bitbucket リポジトリにコミットします。任意のコードをコミットできますが、コミット メッセージに課題のキーを含める必要があります。
この例では、課題のキーは TIS-1
であり、スクリーンショットに表示されているコミット メッセージでこれを参照しています。
3. Jira の課題を再度確認します。課題は「作業前」から「進行中」に変更されているはずです。履歴タブまたはアクティビティタブをクリックすると、課題ステータスを変更した自動遷移を確認することができます。
関連トピック: 開発ツールから Jira へのユーザーのマッピングの仕組み
イベントのハンドリングとイベントの制限
トリガーと他のワークフロー操作/制約との関連性
ステップ 4.トリガーの残りを追加する
これでトリガーを追加およびテストすることができたので、同様な手順で上記リストのトリガーの残りを追加します。
この手順をすべてに設定したくない場合、良い方法があります。Atlassian Marketplace から「トリガーを持つ開発ワークフロー」という、(トリガーが事前に設定されている)同様のワークフローをダウンロードすることができます。
おめでとうございます!これでトリガーを持つワークフローを設定できました。
- トリガーの設定または動作に問題がある場合、以下の「トラブルシューティング」セクションを確認してください。
- トリガーの仕組みについて詳細を知りたい場合は、以下の「トリガーの理解」セクションを参照してください。
トリガーの理解
以下のトピックでは、トリガーの仕組みについての詳細を説明しているため、これらをより効率的に使用することができます。
トリガー イベント
イベント(例:コミット作成)は特定の開発ツールを Jira に統合することでトリガーに使用することができるようになります。以下の表では、各開発ツールで有効になるイベントを一覧表示しています。
開発ツール | Bitbucket、GitHub、GitHub Enterprise | Crucible | Fisheye |
---|---|---|---|
イベント |
|
|
|
There is a known issue where the 'Branch created' event isn't supported for GitHub, which is being tracked under DCON-432 - Getting issue details... STATUS — please keep this in mind when configuring trigger events.
トリガーとグローバル トランジション
トリガーが課題の動作にどのような影響を与えるか正確に理解しているという自信がない限り、グローバル トランジションにトリガーを設定しないことをお勧めします。
グローバル トランジションは、ワークフローの任意のステータスを特定のステータスに遷移できます。これはワークフロー ビューア/エディタで、グローバル トランジションの対象となるステータスを指すすべての黒いひし型で表されます。グローバル トランジションの詳細については、「ワークフローの詳細設定」を参照してください。
グローバル トランジションにトリガーを設定すると、グローバル トランジションの対象のステータスに予期せず遷移するという問題がよく発生するようになります。例えば、「進行中」ステータスに遷移するグローバル トランジションに「コミットの作成」トリガーを設定する場合を考えます。多くの段階で、課題のライフサイクル(例:初期コード作成、レビュー後のコード変更など)中にコードをコミットすることがあります。これにより、「レビュー中」や「完了」などのステータスから「進行中」に不正に遷移するという問題を引き起こす可能性があります。
ヒント: ワークフローにグローバル トランジションを使用する場合、おそらく複数のトランジションが1つステータスに遷移するはずです。これはユーザが課題で複数のワークフロー オプション(例:「開始」と「進行中」)を持つことを意味しています。このオプションを非表示にするには、「ユーザからトランジションを非表示にする」条件を関連するトランジションに追加します。
コミット、ブランチ、プル リクエスト、レビューで Jira 課題を参照する
以下の表では、コミット、ブランチ、プル リクエスト、レビューで Jira 課題を、これらのイベントが課題への遷移を開始するように、照する方法を説明しています(トランジションにトリガーをセットアップする方法を提供しています)。
イベント | 手順 |
---|---|
コミットの作成 | コミットメッセージに課題キーを含めます。 例えば、"TIS-1 初期コミット" というようなコミットメッセージによって、TIS-1 課題が「開始前」から「進行中」へ自動的に遷移します。 |
ブランチの作成 | ブランチを作成する際に、ブランチ名に課題キーを含めます。 たとえば、ブランチに "TIS-2 feature" と名前をつけると、 TIS-2 課題は「作業前」から「進行中」に自動的に移行します 。 |
マージプルリクエストの作成/再オープン/拒否 | プル リクエストに(コミット メッセージで)課題を参照するコミットを含めます。 たとえば、タイトルが "TIS-3 " のプルリクエストを作成すると、"TIS-3" 課題は「進行中」から「レビュー」に自動的にトランジションします 。プルリクエストを再オープン、却下、またはマージすると、それに応じて "TIS-3" 課題はトランジションします。 |
レビューの開始/拒否/廃棄/クローズ | レビューを作成するときに、課題キーをレビュータイトルに含めます。 たとえば、レビューに "TIS- 4New story" という名前をつけて、レビューを開始すると、TIS-4 課題は「進行中」から「レビュー」に自動的に遷移します。レビューを拒否、放棄、またはクローズすると、それに応じて "TIS-4" 課題は遷移します。 |
開発ツールから Jira へユーザをマッピングする
以下のプロセスでは、開発ツールのユーザをワークフロー トリガー用に、Jira ユーザにマッピングする方法を説明しています。これはすべてのイベントに適用されますが、各開発ツールではマッピングに異なるメール アドレスとユーザ名を使用します(以下のプロセスの説明に続く箇条書きを参照してください)。
- プロセス: 開発ツールのイベントを初期化するユーザは、まずメールアドレスでマッチングし、その後ユーザ名でマッチングして Jira にマッピングされます。つまり、
- メールアドレスが一致する Jira ユーザが1人 — Jira ユーザとして課題を遷移させます。
- メールアドレスが一致する Jira ユーザがいない — 匿名ユーザとして課題を遷移させます。
- メールアドレスが一致する Jira ユーザが複数 — ユーザのグループで一致するユーザ名を検索します。ユーザ名が一致するユーザがいる場合、Jira ユーザとして課題を遷移させます。ユーザ名が一致するユーザがいない場合、匿名ユーザとして課題を遷移させます。
ユーザ マッピング用のメールアドレスとユーザ名
イベントのハンドリングとイベントの制限
多くの場合、開発ツールから自動課題遷移へのイベントの処理はシームレスにする必要があります。しかし、時折、イベントのがハンドリングされたりイベントが制限されたりすることで、課題の遷移が遅延したり、課題が全く遷移しなかったりする場合があります。
イベントのハンドリング — イベントは、開発ツールが Jira に DVCS コネクタ経由で接続しているかアプリケーション リンクで接続しているかによって異なるようにハンドリングされます。これは、Jira が利用できない場合にイベントが遅延または消失するかどうかに影響する場合があります。
イベントの制限 — Jira が多数のイベントで過負荷状態にならないように、イベントには制限が設定されています。イベントの制限を超えた後に送信されたイベントは失われます。各開発ツールのイベントの制限については以降の一覧をご確認ください。
トリガーと他のワークフロー操作/制約との関連
トランジションが自動で開始される場合、トランジションに設定されているすべての条件、バリデータ、権限が無視されます。
ただし、事後操作はそのまま実行されます。事後操作がユーザを必要とする場合、そのトランジションは匿名ユーザには実行されないことに注意する必要があります(上記の「ユーザ マッピング」セクションを参照してください)。
トラブルシューティング
トリガーの設定や動作に問題がある場合、以下の手順に従い問題をトラブルシューティングしてください。
1. トリガー診断を使用する
トリガーのトラブルシューティングの最初の手順は JIRA のトリガー診断を確認することです。診断は開発ツールとの接続に問題がある場合や、課題が期待通りに自動的に遷移しない場合に、問題を教えてくれます。
- Jira 管理コンソール > 課題 > ワークフロー > ワークフローの検索に移動し、表示(操作列)をクリックします。
- テキストモード(図表モードではなく)で、目的のトランジションをクリックします。
- トランジション画面(トリガータブが表示されます)で、目的のトリガの詳細を表示をクリックし、診断情報を表示します。
- 「トリガー ソース」セクションには Jira と開発ツール間の統合に関する問題が一覧表示されます。たとえば、設定された認証のタイプが正しいかどうか、などが表示されます。
- 「トランジション失敗」セクションにはトリガーが発火したにも関わらず自動遷移が失敗した課題が一覧表示されます。たとえば、匿名ユーザがトランジションにマッピングされているがトランジションが非匿名ユーザを要求する事後操作を持っているものなどが表示されます。
2. 一般的な問題を確認する
トリガー診断からの情報で問題が解決できない場合、以下の一般的な問題のリストの考えられる原因と解決方法を確認します。
トリガーをトランジションに追加できない:
課題が遷移しない:
課題のトランジションが期待したように実行されません。
トランジションについて記録された情報が正しくありません:
3. ヘルプを活用する
それでも問題を解決できない場合は、アプリ フォーラム、Atlassian Answers、アトラシアンのサポート チームなど、他にも多くのヘルプ リソースを利用できます。
Jira を使いこなす
Atlassian Marketplace の次のようなアプリを使用することで、ワークフローをさらに活用できます。
- Version Released Workflow Trigger: バージョン リリース アクションでのワークフロー トランジションを自動化
- Automated Release Notes for Jira: ニーズに応じて、Jira のトリガーでリリース ノートを生成するようにルールをセットアップ