Mercurial 用 CA Agile Central VCS コネクタのインストールおよびユーザ ガイド

Mercurial から CA Agile Central へのコネクタは、Mercurial システムをスキミングして最近のコミットを探すコードで構成されています。コミット メッセージから情報を抽出し、設定ファイルの仕様に従って CA Agile Central SCMRepository に変更セットまたは変更の情報をポストします。コネクタを会社の 1 つのコンピュータだけにインストールすることは可能ですが、組織の構造、および CA Agile Central に反映する必要のあるリポジトリの数に応じて、コネクタを複数のコンピュータにインストールすることもできます。

コミット メッセージ内にはフォーマット済み ID (US42 など)を配置できます。コネクタは、設定済みのリポジトリのすべてのコミットを処理し、それらのコミットに関する情報を CA Agile Central 内の変更セット オブジェクトおよび変更オブジェクトにプッシュします。コミット メッセージに有効な FormattedID が見つかった場合、コネクタによって作成された変更セットは CA Agile Central 内のそのディフェクト、ストーリー、またはタスクに関連付けられます。

一般的なワークフローとしては、CA Agile Central でいずれかのチーム メンバに DE42 が割り当てられます。これらのメンバがコードを変更してコミットする際には、コミット内に「Found an issue with line breaks - fixed DE42」のようなメッセージを配置します。すると、コネクタはそのコミット メッセージを検索し、コミットに関する情報を CA Agile Central 内のディフェクトにリンクします。このメッセージでは大文字小文字が区別され、「fixed」と「Fixed」は異なります。

このユーザ ガイドの内容は以下のとおりです。

サポートされているプラットフォーム

コネクタは、さまざまなプラットフォームでの実行をサポートします。このソフトウェアは Ruby で作成され、Ruby 2.2.6 を使用してテストおよび認定されています。2018 年 6 月 27 日以降、 以前のバージョンの Ruby では動作しなくなります。このソフトウェアが Linux、Unix、または MacOSX システム上での使用を目的とする場合は、http クライアントおよび rally_api gem のインストール後にインストールする必要があります。

前提条件

  • Ruby 2.2.6 - サポートされているバージョンです。

    このコネクタは、Ruby 2.3.x および 2.4.x とは互換性がない可能性があります。 このコネクタとこれらのバージョンとの互換性は認定されておらず、2.2.6 だけが認定されています。 特定バージョンの Ruby を簡単にインストールして使用するために Ruby バージョン マネージャ ソフトウェア(rvm)を使用する方法を調べることをお勧めします。

  • Ruby 2.0 ~ 2.3 用 Ruby 開発キット(**Windows のみ**)。
  1. ここから、DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe をダウンロードします。
  2. 開発キットの bin ディレクトリへのパスを環境パス変数に追加します。
  3. cd コマンドで、Ruby 開発キットのルート ディレクトリに移動します。
  4. 次のコマンドを実行します: ruby dk.rb init
  5. 次のコマンドを実行します: ruby dk.rb install
  • コネクタを実行するマシンを選択します。
  • コネクタ マシンが Mercurial サーバとは異なるマシンである場合は、サーバのアドレスまたは名前に注意してください。
  • 情報を収集する対象のリポジトリへのパスを収集します。
  • 情報の移動先となる CA Agile Central のワークスペースを選択します。
  • Mercurial サーバと ssh

    主なユース ケースとしては、このコネクタが、Mercurial ソフトウェアおよびリポジトリが存在するプラットフォーム上で実行されます。Mercurial プラットフォーム以外のプラットフォームでこのコネクタを実行することはできますが、そのユース ケースでは、ssh を使用することと、公開鍵と秘密鍵の情報を適切にセットアップすることを想定しています。ssh およびキー ファイルのセットアップは、このドキュメントの範囲外です。ssh および PKI に関するドキュメントについては、インターネットを参照してください。

    Windows でコネクタを実行している場合、リモート ボックスに接続するには、ssh の実行可能ファイルが必要となります。Cygwin、Windows 用 Git インストーラなどのパッケージには、ssh.exe が含まれます。リモート リポジトリまたはサーバに正常に接続するには、その ssh.exe の場所を PATH 環境変数に追加する必要があります。

    Windows に対して実行可能ファイルを使用している場合、それ以上の前提条件はありません。Ruby ソースを実行する場合は、コネクタを実行するマシンに Ruby バージョン 2.0.0 以降をインストールする必要があります。rubyinstaller.org から Windows Ruby インストーラを取得するか、または Linux および Unix のユーザの場合は rvm.io から rvm を使用することをお勧めします。

    コネクタのダウンロード

    コネクタをダウンロードするには、ここの手順に従います。

    コネクタのインストール

    インストーラとオペレータ ファイルシステムの権限

    このコネクタは、cron または Windows タスク スケジューラ(WTS)によって開始され、継続的に実行することを目的としているので、コネクタのインストールにおけるディレクトリおよびファイルの権限と ACL に関して、コネクタをインストールするユーザの ID と、cron または WTS による実行時のユーザの ID を考慮する必要があります。コネクタのランナーは、すべてのファイルを読み取ることができ、configs サブディレクトリと logs サブディレクトリに書き込むことができる必要があります。

    配布コンテンツ

    1715 5 月 23 日 13 時 01 分 ライセンス
    18419 5 月 23 日 13 時 01 分 README
    4811 5 月 23 日 13 時 02 分 ユーザ マッピング方法
    170 5 月 23 日 15 時 43 分 設定
    136 5 月 23 日 13 時 02 分 拡張
    170 5 月 23 日 13 時 02 分 gem
    1897 5 月 23 日 13 時 02 分 git2ca_agile_central.rb
    2115 5 月 23 日 13 時 02 分 install_gems.rb
    102 5 月 23 日 13 時 02 分 ライブラリ
    136 5 月 23 日 15 時 36 分 ログ
    374 5 月 23 日 13 時 02 分 プラグイン
    43520 5 月 23 日 13 時 02 分 vcseif-1.6.0.gem
     
    
    

    インストール

    1. ソフトウェアをインストールする適切なディレクトリ内に、git2ca_agile_central-(バージョン)-master-(ビルド番号).zip ファイルを解凍します。
    2. 環境変数 GEM_COMMAND を、Ruby インストール ディレクトリにある gem 実行可能ファイルに設定します。以下に、Linux と Windows 上の場所の例をそれぞれ示します。
      • /myhome/.rvm/rubies/ruby-2.2.6/bin/gem
      • C:\Ruby226\bin\gem
    3. install_gems.rb Ruby スクリプトを実行して、関連するすべての gem をインストールします。「 書き込み権限がありません」のような出力が表示された 場合は、 システム管理者に問い合わせて 必要な権限を取得(通常は sudo または他の類似 ソフトウェアを使用)するか、またはシステム管理者に install_gems.rb コマンドの実行を依頼します。 コマンドをコンソールまたはターミナル ウィンドウのプロンプトで実行するには、以下のように入力します。 ruby install_gems.rb

    Mercurial の設定

    CA Agile Central に Mercurial 履歴をどの程度反映するかを検討する

    Mercurial 内のコミットの完全な履歴を反映するようコネクタを操作することは可能です。CA Agile Central にコミットの完全な履歴を反映する必要があるか、またはある特定の時点の履歴だけを反映するかに関して、組織にとって効果的な戦略に到達するのに役立つ、考慮事項、理由、および利点のプロコン リストを収集する必要があります。

    CA Agile Central の設定

    ターゲット WorkspaceConfiguration に対して BuildandChangsetEnabled が設定されていることを確認する

    CA Agile Central ワークスペースの管理者は、ターゲット ワークスペースに対してこれを有効にする必要があります。これが有効でない場合、コネクタは機能しますが、CA Agile Central 作業アイテム(ストーリー、ディフェクト、タスク)に関連付けられている変更セットまたは変更の情報は表示されません。

    コネクタの設定

    configs 内の sample.yml ファイルを新しい名前(たとえば、repo_one.yaml)にコピーします。コピーしたファイルを編集し、サーバ、認証情報ワークスペース、リポジトリ名、およびパスのいくつかのサンプル値を、ご使用の環境に適した値に調整します。ファイルは YAML 形式です。YAML 形式では、インデントを使用して構造を表し、コロン(:)とダッシュ(-)を使用して名前と値の区切りおよびリスト要素を示します。編集したファイル内でこれらの構文要素を保持するよう注意してください。

    YAML 設定ファイルの Rally セクション内には、変更セット/変更アイテムを関連付ける CA Agile Central システム内の SCMRepository を指定できるエントリが 存在します。この SCMRepository は、コネクタの実行前には存在する必要のない、名前付きのコンテナです。これが存在しない場合、コネクタは、CA Agile Central ユーザのターゲット ワークスペース内に SCMRepository を作成します。

    設定ファイルの CA Agile Central セクションと Mercurial セクションの一方または両方に表示できる、オプションの Lookback 設定アイテムがあります。このパラメータの値は、分(デフォルト、または「m」文字を使用)、時間(「h」文字を使用)、または日数(「d」文字を使用)で表されます。例: Lookback: 90 Lookback: 120 m Lookback: 8 h Lookback: 10 d

    Lookback 値を明示的に指定しない場合、コネクタはデフォルト値である 1 時間を使用します。CA Agile Central では、どちらかのセクションで Lookback の値を指定した場合、もう一方のセクションでも同じ値を使用して Lookback を指定することをお勧めします。Lookback の値が同一ではない場合、状況によっては、Mercurial からの変更セットが CA Agile Central に反映されない可能性があります。これは、コミットがマスタ リポジトリにプッシュされた時刻ではなく元のコミット時刻を記録するという配布バージョン管理システムの性質のほか、コネクタがこのようなコミットを取得するための考慮時間ウィンドウが短すぎることに原因があります。

    Mercurial システム内と CA Agile Central サブスクリプション内で、ユーザ名がどの程度似ているか、または異なるかを評価します。両方のシステム内でユーザ名が普遍的に同一である場合は、Transforms セクション下のすべての Author サブアイテムをコメント化するか、または Transforms セクション内の Author フィールドの値を「Passthru」に設定することができます。その一方で、Mercurial ユーザの値を対応する正しい CA Agile Central ユーザ名の値に変換できる確定的なマッピングが存在する場合は、Author の変換値を適切なクラス名に調整する必要があります。特定の状況に適合する方法を判断するには、ユーザ マッピング方法のテキスト ドキュメントを参照してください。

    Author の適切な変換方法を特定したら、その変換を実装する Ruby クラス名を識別するよう設定を編集する必要があります。Ruby クラス名は、plugin サブディレクトリ内のファイル内にある Ruby ソース コードのファイルに存在する必要があります。

    VCS リポジトリへの SCMRepositories のマッピング

    VCS コネクタは、CA Agile Central SCMRepository と VCS リポジトリ(Git、GitHub、Subversion、Mercurial など)の間で 1 対 1 の関係を維持して動作するよう設計されています。VCS コネクタは実行時に、コネクタ設定ファイル内の固有の値に対して、CA Agile Central SCMRepository アイテムを作成します(まだ存在しない場合)。これにより、新しいリポジトリを指定している設定を実行する前に CA Agile Central SCMRepository アイテムを作成する必要がなくなる点で、管理の負担が多少軽減されます。1 対多のマッピングでは、パフォーマンスの問題が発生する可能性があります。

    各リポジトリには、設定ファイルと時間ファイルがあります。時間ファイルは、リポジトリに関して最後から 2 番目のコミットのタイムスタンプを記録します。たとえば、昨秋に大量のコミットがあったが、それ以降コミットのない Apricot リポジトリがあり、また、過去数か月間にアクティビティのあった Banana リポジトリがあるとします。これら 2 つのリポジトリのコミットが、単一の CA Agile Central SCMRepository に組み込まれると、以下の効果があります。Apricot リポジトリの設定を処理する際には、Apricot の時間ファイル内の値として recent が定義されている条件下で、CA Agile Central 内の最近の変更セット レコードを検索します。そのリポジトリへの前回のコミットが昨秋であったので、単一の SCMRepository から過剰な量の情報が読み取られます(Apricot の変更セットだけでなく、昨秋以降のすべての変更セットを参照しているため)。

    リポジトリ設定ファイルの例:

    [code] --- VCSConnector: Rally: Server : us1.rallydev.com Protocol : https Username : [email protected] Password : 22333four # APIKey : _hgiotewhgeiwhgh325930503453490 # can be used in place of Username / Password entries Workspace : VanillaBean RepositoryName : Balloon # Proxy : some_proxy.yoursite.com:9876 # or an IP address:port # ProxyUser : outbound # ProxyPassword : bvc-357%GNQ Lookback : 90 # in minutes by default, use m/h/d suffix for minutes/hours/days UpdateArtifactState : False StateExtractorClass : BasicActionsAndArtifactsExtractor(message) Debug : False Mercurial: # Server : HGsvr.company.com # specified if repo is not local RepositoryBase : /var/www/foo/bar Lookback : 90 MaxItems : 100 # RevURI : http://yourserver.com:8008/hgifc/bigproject/rev/{revnumber} # if running web access to Hg repo # FileURI : http://yourserver.com:8008/hgifc/bigproject/file/{revnumber}/{filepath} # if running web access Debug : False Services: Preview : False LogLevel : Debug Transform: Author : Passthru ... [/code]

    システムで Web フロント エンドを使用している場合、Mercurial セクション下の RevURI および FileURI は ルート URI であることを想定しています。URI は、変更セットおよびファイルへのリンクのベースとして 使用されます。たとえば、ルートが http://server:port/Mercurial/rev/ である場合、 CA Agile Central で、変更セット 12345 に対して変更セットのリンクが http://server:port/Mercurial/rev/12345 として作成されます。 文字列 {revnumber} および {filepath} は、CA Agile Central に格納されるリンクをコネクタが作成すると置換されます。

    プロキシ* アイテムは、アイテムの前に # を使用してコメント化されています。 YAML ファイル内で、# 文字で始まるすべての行が無視され、 # 文字シーケンスに続くすべてのコンテンツが無視されます(# シーケンスを含む)。

    CA Agile Central API キーの作成

    CA Agile Central API キーを作成して、ユーザ名とパスワードを使用せずにサブスクリプションのデータにアクセスするために使用することができます。

    コネクタで API キーを使用するには、config.yml ファイルで Rally セクションを編集し、APIKey 行を追加します。APIKey 設定エントリを指定する際には、Rally 設定セクションからユーザ名とパスワードを省略します。APIKey エントリが存在する場合、ユーザ名とパスワードは使用されず、これらが設定ファイルに含まれればログ ファイルに警告が表示されます。APIKey エントリの値が無効、空白、または nil の場合でもこのことが当てはまります。サブスクリプションの管理者が、お客様のサブスクリプションを SSO 専用に設定した場合、指定の APIKey 値に関連付けられているユーザを、権限のあるユーザのホワイトリストに追加する必要はなくなりました。

    コネクタは、rally_api バージョン 1.2.1 を使用するようになりました。指定された APIKey はフル アクセス権を持つ必要があり、読み取り専用の api キーでは、コネクタが CA Agile Central への書き込みを行うことはできません。

    フル アクセス API キーを作成するには、「CA Agile Central Application Manager」を参照してください。

    コネクタの実行

    注: リポジトリ内に少なくとも 1 つのコミットが含まれるまで、コネクタの実行を延期する必要があります。

    設定ファイル(たとえば、「repo_one.yaml」)の Services セクション内に、 False に設定されている Preview のエントリがあります。初期のセットアップ段階でこの値を True に 設定することをお勧めします。これにより、指定した認証情報および情報を使用してコネクタが CA Agile Central に 正常に接続できることを確認できるほか、 hg コマンドの使用を検証できます。PATH 環境変数には、hg コマンドが存在するファイルシステム パスを含める必要があります。*nix cron ジョブ(または Windows タスク スケジューラ エントリ)内で使用する環境変数を設定する方法については、 Linux/Unix/MacOSX/Windows のドキュメントを参照してください。 プレビュー モードで実行されるコネクタが想定どおりに動作すると判断できたら、 設定内の Preview 値を False に設定できます。

    継続的に cron/Windows タスク スケジューラ(またはその他のジョブ タスク スケジューリング ソフトウェア)を使用して、コネクタを定期的に実行できます。CA Agile Central では、最初に、通常の営業時間には 15 分ごと、営業時間外にはより低い頻度でコネクタを実行することをお勧めします。

    configs サブディレクトリには多数の設定ファイルが含まれる可能性があり、名前またはグロビング(ワイルドカードの構文)によって呼び出すよう指定できます。例: ruby hg2_agile_central.rb apricot banana cherry dogwood ファイル apricot.yml、banana.yml、cherry.yml、および dogwood.yml は configs サブディレクトリに存在する必要があります。コネクタは、インストール ベース ディレクトリ下の configs サブディレクトリ内の設定ファイルだけを検索します。

    コネクタが実行されるたびに、logs/hg2rally.log ファイル内に呼び出しを示すエントリが作成されます。呼び出しで指定される設定ごとに、その設定の実行からのリターン コードを記録するエントリがファイル内に生成されます。すべて設定についてコネクタの実行が終了すると、コネクタの実行の完了を示すエントリが書き込まれます。

    また、logs サブディレクトリ内で、指定される設定ごとに、実行中に発生したアクティビティに関する詳細情報を含むファイルが作成されます。設定ファイルで LogLevel 値を変更することにより、これらのログ ファイルに書き込まれる詳細レベルを調整できます。通常、LogLevel は Info に設定されます。コネクタが正常に完了しない状況が発生した場合は、LogLevel を Debug に調整し、コネクタを実行してトラブルシューティング プロセスを開始できます。これらのログ ファイルは、ケースの調査の効率を高めるために CA Agile Central サポートに送信できます。

    コネクタは、設定名に対応するベース インストール ディレクトリ内で、コミットが前回処理された日付を含めてファイルを作成します。ファイルは config_time.file と名付けられ、YYYY-mm-dd HH:MM:SS Z (Zulu 時間)の形式の時間エントリを含みます。最初の実行時には、設定の時間ファイルは存在せず、コネクタはデフォルトで 2010-01-01 00:00:00 Z 以降に発生したコミットを検索します。その動作をオーバーライドするには、処理しようとしている設定の時間ファイルを作成および編集します。上記の形式のエントリを指定することで、コミット処理の開始時点を制御できます。

    コネクタの拡張

    インストールの extension サブディレクトリ内にある statex.rb という名前のファイル内に、サンプルの Ruby クラスが存在します。そのファイルに含まれているクラス定義の名前は BasicActionsAndArtifactsExtractor です。このサンプル クラスは、コミット メッセージを調査したり、Rally アーティファクト識別子および状態遷移ターゲット値を抽出する基本的な方法を示します。設定ファイルのアイテム UpdateArtifactState の値が True に設定されている場合にこのクラスを使用すると、識別されたアーティファクトの State (または、UserStory の場合は ScheduleState)が、コミット メッセージに記載されている状態値に遷移します。

    たとえば、コミット メッセージに CA Agile Central のディフェクト(DE1987 として識別される)が記載されていて、その直前または直後に新しい有効な状態値が含まれる場合、コネクタは、CA Agile Central 内の識別されたアーティファクトの State をその状態に変更します。

    例: hg commit my_file.java -m "Fixed DE1987 by changing preamble paragraph 3"

    コネクタのコミットおよび実行の前に CA Agile Central のディフェクト DE1987 の状態がオープンであった場合、この特定の変更セットを処理するコネクタの操作以降、CA Agile Central のディフェクト DE1987 の状態は「Fixed」として表示されます。このメッセージでは大文字小文字が区別され、「fixed」と「Fixed」は異なります。

    extension サブディレクトリは、提供されている例がユーザの慣習に適合しない場合、CA Agile Central のアーティファクト識別子および状態変更を抽出する、ユーザ独自のメッセージ処理を提供できます。拡張は、Ruby で記述されたクラスでなければならず、サービスと呼ばれるインスタンス メソッドを提供する必要があります。このサービスは、コミット メッセージを引数として指定し、状態名(Fixed、Completed など)をキーとするエントリと共に Ruby Hash インスタンスを返すか、または CA Agile Central のアーティファクト識別子(FormattedID)によって取り込まれる関連値として Ruby Array と共に nil を返す必要があります。

    サポート

    質問、問題、または提案がある場合は、CA Agile Central の任意のページの下部にある[サポート]リンクをクリックしてサポートにお問い合わせください

    リビジョン履歴

    • 1.6.0-master --- 2018 年 5 月 25 日
      • 機能強化:
        • 統合ディストリビューション、TLS V1.2 のサポートに Ruby 2.2.6 の使用が必要です。
    • 1.5.3-master --- 2017 年 12 月 12 日
      • 機能強化:
        • すべての vcs-eif コネクタを同期します。
    • 1.5.1-master --- 2017 年 9 月 12 日
      • 機能強化:
        • 変換の対象となるフィールドにメッセージが追加されました。
        • Ruby 2.2.6 での使用が保証されました。
    • 1.4.3-master --- 2016 年 10 月 24 日
      • 機能強化:
        • 1 つのコミット後に処理を行えるようロジックが更新されました。
    • 1.4.1-master --- 2016 年 10 月 17 日
      • 修正:
        • 空のリポジトリを処理する際にキャッチされなかった例外に対処されました。
    • 1.4.0 - master-1046 (2015 年 11 月)
      • 機能強化:
        • ブランドの再設計。
    • 1.3.2 - master-1043 (2015 年 8 月)
      • 機能強化:
        • APIKey エントリの使用に対するサポートが追加され、現在もサポートされている ApiKey の使用よりも優先してこの APIKey の使用を奨励するように
          ドキュメントが改訂されました。
    • 1.3.1 - master-1040 (2015 年 7 月)
      • 機能強化:
        • CA Agile Central の任意のユーザ名値を小文字に変換する機能のサポートが追加され、
          CA Agile Central およびターゲット VCS システムからの取得のシーケンスが反転して、rally_api に対する依存関係が 1.2.1 に更新されました。
    • 1.3.0 - master-1040 (2015 年 4 月)
      • 修正:
        • CA Agile Central の変更セット メッセージ フィールドの長さ制限である 4000 バイトを超える長さのマルチバイト文字を含む、コミット メッセージを処理します。
      • 機能強化:
        • rally_api に対する依存関係が 1.2.0 に更新されました。
    • 1.2.9 - master-1039 (2015 年 3 月)
      • 修正:
        • JSON エンコーディング拡張に対応するために 4000 文字を超えるコミット メッセージの処理が調整されました。
    • 1.2.8 - master-1038 (2015 年 3 月)
      • 機能強化:
        • 角かっこで囲まれたコミット メッセージ内のアーティファクト識別子を識別する機能が向上しました。
    • 1.2.6 - master-1037 (2015 年 1 月)
      • 機能強化:
        • rally_vcs_connection.rb configureExtensionEnvironment および statex.rb がカスタム アーティファクト プレフィックスに対応するよう更新されました(ディフェクトの場合「BUG」など)。
        • rally_api に対する依存関係がバージョン 1.1.2 に更新されました。
    • 1.2.5 - master-1035 (2014 年 10 月)
      • 機能強化:
        • CA Agile Central Web サービス API v2.0 および更新済みの rally_api gem を使用するよう更新されました。
    • 1.2.4 - master-1033 (2014 年 9 月 16 日)
      • 機能強化/修正:
        • 設定ファイルの CA Agile Central 部分でユーザ名とパスワードの代わりに API キーを使用するためのサポートが追加されました。
        • rally_api ツールキット バージョン 1.0.1 に更新されました。
    • 1.2.3 - master-1030 (2014 年 8 月 19 日)
      • 機能強化/修正:
        • DE21993 を修正 - CA Agile Central のコミット メッセージ フィールドの 4000 文字という制限に対応するために、コミット メッセージがこの文字制限を超える場合、制限を超えた文字が切り捨てられます。切り捨てが発生すると、コミット メッセージに切り捨ての注釈が追加され、ログ ファイルに警告メッセージが表示されます。

    フィードバック

    ヘルプをお求めですか?CA Agile Central コミュニティは、セルフサービスとサポートのワンストップ ショップです。CA Agile Central サポートにフィードバックを送信したり、答を見つけたり、他のユーザとのコラボレーションには CA Agile Central コミュニティ にご参加ください。