GitLab Jiraインテグレーション
GitLab イシューは、アイデアを議論したり、作業を計画・追跡したりするための強力なツールです。 しかし、多くの組織ではこれらの目的に Jira を使用しており、Jira には広範なデータやビジネスプロセスが組み込まれています。
JiraからGitLabイシューにコンテンツやプロセスを移行することもできますが、Jiraを使い続け、インテグレーションを通じてGitLabと一緒に使うこともできます。
Jiraとのインテグレーションについては、JiraイシューとJenkinsパイプラインによるGitLabワークフローをご覧ください。
GitLab プロジェクトを Jira インスタンスと統合すると、GitLab プロジェクトと Jira のプロジェクト間のアクティビティを自動的に検出し、相互参照することができます。 これには、GitLab で作業が完了したときに Jira イシューをクローズまたは移行する機能が含まれます。
GitLab で以下のアクションを実行したときのインテグレーションの反応を示します:
- コミットメッセージまたは MR (マージリクエスト) にJiraイシューID を記載します。
- GitLab は Jira イシューにハイパーリンクします。
- Jira issue は GitLab のコミット/MR にイシューリンクを追加します。
- Jira へのコメントを無効にしていない限り、Jira イシューには GitLab でのコメントを反映したコメント、コメント作成者、GitLab でのコミット/MR へのリンクが追加されます。
-
コミットまたは MR が JiraイシューID を ‘クローズ’、’解決’、’修正’ したことを示します。 プロジェクトのデフォルトブランチ (通常は master) でコミットが行われたとき、または変更がデフォルトブランチにマージされたとき:
- GitLab のマージリクエストページには、イシューへのリンクとともに Jira イシューを “Closed” したことが表示されます (注意: マージの前に、MR は Jira イシューを “Closes” したことを表示します)。
- Jira 課題はアクティビティを表示し、Jira 課題はクローズされるか、またはその他の方法で移行されます。
GitLabと Jira をインテグレーションする方法とその理由の記事で説明したように、GitLab から直接Jira のスマートコミットを使うこともできます。
設定
各 GitLab プロジェクトは、Jira インスタンス全体に接続するように設定することができます。 つまり、1 つの GitLab プロジェクトは、一度設定すれば、そのインスタンス内の_すべての_Jira プロジェクトと相互作用することができます。 したがって、GitLab プロジェクトを単一の Jira プロジェクトと明示的に関連付ける必要はありません。
Jira インスタンスが 1 つの場合、デフォルトのテンプレートで設定ページを事前に埋めることができます。サービス テンプレートドキュメントを参照してください。
GitLab で Jira サービスを有効にするには、まず Jira でプロジェクトを設定し、GitLab で正しい値を入力する必要があります。
Jira の設定
Jira サーバー
Jira Serverはベーシック認証に対応しており、接続時にはユーザー名とパスワードが必要です。 CAS 経由で Jira Server に接続することはできませんのでご注意ください。 まずJira Server でユーザーを設定してから GitLab の設定に進みます。
Jira Cloud
Jira Cloudは API トークンによる認証をサポートしています。Jira Cloudに接続する場合、メールアドレスと API トークンが必要です。 まずJira Cloud でユーザーを設定し、GitLab の設定に進みます。
GitLab の設定
注:
- 現在サポートされている Jira のバージョンは
v6.x, v7.x, v8.x
です。 GitLab 7.8 以上が必要です。- GitLab 8.14では、Jiraとインテグレーションする新しい方法が導入され、入力しなければならない設定オプションが大幅に簡素化されました。 古いバージョンを使用している場合は、このドキュメントに従ってください。
- Oracle の Access Manager をサポートするために、GitLab は Basic Auth を有効にするために追加のクッキーを送信します。各リクエストに追加されるクッキーは
OBBasicAuth
で、値はfromDialog
です。
プロジェクトで Jira インテグレーションを有効にするには、[インテグレーション] ページに移動し、[Jiraサービス] をクリックします。
項目 | 説明 |
---|---|
Web URL
| このGitLabプロジェクトにリンクされているJiraインスタンスウェブインターフェースのベースURL。 例:https://jira.example.com .
|
Jira API URL
| Jira インスタンス API へのベース URL。設定されていない場合、Web URL の値が使用されます。 インスタンスンスンスhttps://jira-api.example.com .Jira Cloudを使用している場合、このフィールドは空白のままにします (またはWeb URL の同じ値を使用します)。
|
Username/Email
|
Jira ステップ設定時に作成されます。Jira Serverにはusername を、Jira Cloudにはemail を使用してください。
|
Password/API token
|
password forJiraServer またはAPI token forJiraCloud を使用してください。
|
Transition ID
| これは課題を希望の状態に移動するトランジションの ID です。, または; で区切ってトランジション ID を挿入することが可能で、指定した順序で課題が各状態に移動することを意味します。ID を正しく設定しないと、コミットまたはマージリクエストによる Jira 課題のクローズは機能しません。
|
トランジションIDの取得
最新の Jira ユーザー インターフェイスでは、ワークフロー管理 UI でトランジション ID を見ることができなくなりました。 必要な ID は次のいずれかの方法で取得できます:
- APIを使用し、
https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions
のようなリクエストで、適切な「オープン」状態にあるイシューを使用します。 - 必要なトランジションのリンクにマウスオーバーし、URLの “アクション “パラメーターを探します。
トランジションIDは、変更先のステータスが同じでも、ワークフローによって異なる場合があることに注意してください(例:バグとストーリー)。
設定を保存すると、GitLab プロジェクトは Jira インスタンス内のすべての Jira プロジェクトとやり取りできるようになり、GitLab プロジェクトのページに適切な Jira プロジェクトへ移動する Jira リンクが表示されるようになります。
Jira イシューのコメントを無効化
Jiraイシューを参照すると、常にGitLabのソースコミット/MRにリンクされますが、GitLabがJiraイシューにコメントをクロスポストするかどうかをコントロールすることができます。 この機能はデフォルトで有効になっています。
Jira イシューへの自動コメントを無効にします:
- インテグレーションページを開き、Jiraを選択します。
- イベントアクション]セクションで、[コメント]のチェックを外します。
イシュー
ここまでで、Jira の設定とGitLab での Jira サービスの有効化が完了しているはずです。 すべてが正しく設定されていれば、GitLab のコミットやマージリクエストで Jira の ID を指定するだけでイシューを参照したり閉じたりできるはずです。
Jira イシューの参照
GitLabプロジェクトにJira issue trackerが設定され、有効になっている場合、GitLabでJira issueに言及すると、自動的にJira issueにGitLabへのリンクを含むコメントが追加されます。 つまり、マージリクエストやコミットでissueを参照するコメント、例えばPROJECT-7
、Jira issueにそのフォーマットのコメントが追加されます:
USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
ENTITY_TITLE
-
USER
イシューに言及したユーザー。 GitLabのユーザープロファイルへのリンクです。 -
LINK_TO_THE_COMMENT
Jira イシューが言及されたエンティティの名前を含む言及元へのリンクです。 -
RESOURCE_NAME
イシューを参照したリソースの種類。 コミットまたはマージリクエストである可能性があります。 -
PROJECT_NAME
GitLabプロジェクト名。 -
ENTITY_TITLE
マージリクエストのタイトルまたはコミットメッセージの最初の行。
たとえば、以下のコミットはPROJECT-1
を ID とする Jira イシューを参照します:
git commit -m "PROJECT-1 Fix spelling and grammar"
Jira イシューのクローズ
コミットやマージリクエストでトリガーワードを使用することで、GitLab から直接 Jira イシューをクローズすることができます。 トリガーワードに続いてコミットメッセージに Jira イシュー ID を含むコミットがプッシュされると、GitLab は言及された Jira イシューにコメントを追加し、直ちにクローズします (トランジション ID が正しく設定されている場合)。
現在、3つのトリガーワードがあり、どちらを使っても同じ目的を達成することができます:
Resolves PROJECT-1
Closes PROJECT-1
Fixes PROJECT-1
PROJECT-1
は Jira イシューの ID です。
注:
- プロジェクトのデフォルトブランチ (通常はmaster) へのコミットおよびマージのみが Jira でイシューをクローズします。 プロジェクトのデフォルトブランチはプロジェクト設定で変更できます。
- Jira イシューが解決済みである場合は移行されません。
Jira イシューのクローズ例
次の例を考えてみましょう。
- Jira の
PROJECT
というプロジェクトについて、新しい機能を実装し、GitLab にマージリクエストを作成しました。 - この機能は Jira issue
PROJECT-7
でリクエストされたもので、GitLab のマージリクエストには改善が含まれています。 - マージリクエストの説明では、イシュー終了トリガー
Closes PROJECT-7
を使用しています。 - マージリクエストがマージされると、Jira 課題はコメントと課題を解決したコミットへの関連リンクとともに自動的にクローズされます。
次のスクリーンショットでは、Jira イシューへのリンク参照がどのように見えるかを確認できます。
このマージリクエストがマージされると、Jira 課題は課題を解決したコミットへのリンクとともに自動的にクローズされます。
トラブルシューティング
これらの機能が期待通りに動作しない場合は、インテグレーション設定の方法に問題がある可能性があります。
GitLab は Jira イシューにコメントできません。
インテグレーション用に設定した Jira ユーザーが、Jira 課題にコメントを投稿したり、GitLab にもできるようにしたい場合は、課題を移行したりできる正しいアクセス権限を持っていることを確認してください。 GitLab 課題トラッカーが無効になっている場合、Jira 課題の参照とコメントの更新は機能しません。
GitLab が Jira イシューを閉じることができません。
Jira 設定で設定したTransition ID
が、プロジェクトがイシューをクローズするために必要なものと一致していることを確認してください。
Jira 課題がすでに解決済みとマークされていないこと、つまり Jira 課題解決フィールドが設定されていないことを確認してください (Jira リストでは取り消し線が引かれていないはずです)。
キャプチャ
CAPTCHA は、Jira インテグレーションをテストする際、401 unauthorized
エラーにつながるログイン試行が何度か連続して失敗した後にトリガーされることがあります。 CAPTCHA がトリガーされた場合、Jira サイトで認証するために Jira の REST API を使用することはできません。 Jira インスタンスにログインし、CAPTCHA を完了する必要があります。