VSTS/TFS 2017 向け VCS コネクタ

概要

VSTS/TFS 2017 向け CA Agile Central VCS コネクタは、VSTS および TFS 2017 のコミットに関する情報を CA Agile Central にポストし、関連するアーティファクトを特定するのに十分な情報が VCS コミット メッセージに含まれている場合、これらのコミット内容を CA Agile Central の変更セットおよびアーティファクトに関連付けます。このコネクタは、TFS サーバがバージョン管理に git を使用するように設定されている場合、TFS 2017 と連携して動作します。また、このコネクタは、コミット メッセージに適切な構文(たとえば、「US123 進行中」)が含まれている場合、関連する CA Agile Central アーティファクトの状態(具体的には、ディフェクトの状態やユーザ ストーリーのスケジュール状態)を更新します。VSTS/TFS 2017 向けの CA Agile Central VCS コネクタは、一方向および 1 回限りのメカニズムに分類されます。VSTS および TFS 2017 内の情報は変更されません。情報は Agile Central にのみ書き込まれ、データの重複が行われたり許可されることはありません。

Agile Central VCS コネクタには、設定オプションがターゲットの設定ファイルに存在する場合、VSTS および TFS の取得準備リクエスト アイテムの作成を検出し、Agile Central の対応する取得準備リクエスト アイテムをポストする機能が含まれています。

VSTS/TFS 2017 向けの Agile Central VCS コネクタは、必要なスケジュールに従ってご使用のプラットフォーム上で実行するソフトウェアで構成されています。コネクタの設定はポリシーベースです。つまり、コネクタの動作対象となる VSTS または TFS リポジトリごとに個別の設定ファイルを指定する必要はありません。ポリシーベースという特徴により、VSTS プロジェクト内の(またはコレクション内の TFS ユーザがアクセス可能な)リポジトリのすべてまたは一部のスコープを設定できます。

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

ソフトウェア要件

  • VSTS の場合 - VSTS REST API アクセス用の個人用セキュリティ トークンとアクティブな VSTS アカウント。

  • TFS 2017 - TFS 2017 REST API アクセス用の個人用セキュリティ トークンと、TFS 2017 インスタンスへのアクセス。

  • Linux、MacOS、または Windows が実行されているコンピューティング プラットフォーム。
  • Python 3.5.x または 3.6.x (3.6.x が推奨されます。Windows ユーザの場合、64 ビット バージョンの使用を推奨します)。パッケージ/インストーラは、www.python.org から取得できます。

  • Windows のみの追加の要件

コネクタのダウンロード

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

ハードウェア

コネクタは、いくつかの方法でインストールできます。並行して実行できる同じマシン上に複数のインストール場所を指定することができ、その条件によって必要なハードウェアが決まります。以下のガイドラインに従うことを推奨します。

  • コネクタが実行されるコンピューティング プラットフォーム(Windows、Linux、Mac)
  • クアッドコア プロセッサ セットと最低 8 GB の RAM を備えた基本ハードウェア
  • インストール場所ごとに 20 ~ 25 個の設定ファイル
  • コネクタの実行で生成されたログ ファイルを保存するのに十分なディスク ストレージ容量。1 GB の空きディスク容量を推奨します。
  • 並行して実行するインストール場所をさらに追加する場合は、インストールされた場所ごとに、実行時に最大 200 MB の RAM を消費し、アイドル状態では 50 MB 未満の RAM を消費します。
  • 必要なハード ドライブの容量は最小限であり、ログ ファイルが増加した場合にのみ拡張する必要が生じるので、インストール場所あたり 200 ~ 250 MB の容量を推奨します。

インストール

 

** VSTS または TFS 設定のサンプル ファイルと、このコネクタで利用可能なすべてのオプションを参照するには、このドキュメントの一番下の「サンプルのダウンロード」に移動してください。

 

  1. ご使用の環境で Python 3.5.x または 3.6.x が利用可能である必要があります。
  2. 以下のコマンドを実行します。 
    pip3 install requests==2.18.4
    pip3 install pyral==1.4.0
    pip3 install PyYAML==3.12
    pip3 install cryptography==1.7.1
  3. vcsconn-2.0.0.zip を解凍します。cd コマンドを使用して、作業ディレクトリを、コネクタをインストールするディレクトリに変更します vcsconn-2.0.0.zip を解凍します(または .zip ファイルを解凍できる適切なプログラムを使用します)。 
    cd vcsconn-2.0.0.zip
    ls -laR # 解凍されたコンテンツを確認します。Windows では dir を使用します
    
       vcsconn                     # vcsconn モジュールのルート ディレクトリ
       vcs2ac                      # コネクタ起動スクリプト。これが実行するファイルになります
       config                      # このコネクタで使用する設定ファイルを保持します
          sample_vsts.yml          # 参照の基準として使用するサンプル設定ファイル 
          sample_user_map.yml      # ユーザ マッピングのサンプル テキスト ファイル
       log                         # 設定ごとにログ ファイルと時間ファイルを保持します
       README_VSTS.txt             # このファイル
       User-Mapping-Strategies.txt # VSTS/TFS 2017 ユーザと AC ユーザ名のマッピング戦略の詳細

セットアップ

一般的な推奨事項

  1. シンプルに開始します。

  2. VSTS/TFS 2017 と Agile Central サブスクリプションのセットアップと管理に最も精通しているユーザを見つけます。
  3. configuration サブディレクトリを見つけます。

  4. sample_vsts.yml または sample_tfsgit.yml ファイルを、環境に合わせて名前が付けられたファイルにコピーします。たとえば、cp sample_vsts.yml to product_x.yml (または他の適切な名前が付けられた、拡張子が .yml のファイル)。

  5. product_x.yml ファイルを編集します。たとえば、認証情報、ワークスペース、プロジェクト、トークンなどのサンプル値を、ご使用の環境に適した有効な値に変更します。

  6. 適切な SecurityLevel を決定します。

  7. コミット メッセージに基づいて CA Agile Central アーティファクトの状態を更新するかどうかを決定します。

  8. VSTS または TFS コミッタを有効な Agile Central ユーザにマップするかどうかを決定し、Passthrough、FileBasedUserNameLookup、または UserNameDomainAugmentLookup の 3 つのマッピング方法のいずれかを選択します。

  9. 特定のユーザまたは名前付き組織のリポジトリを処理するかどうかを決定します。

 

       * 設定ファイルの構文については、「付録 A」を参照してください。

操作

手動

ターミナル ウィンドウまたはコンソールを使用: cd コマンドでインストールのルート ディレクトリに移動します(たとえば、/opt/local/sw/vcsconn-2.0.0)。その後、python3 vcs2ac product_x.yml を実行します。このソフトウェアでは、設定ファイルが configuration サブディレクトリ内に存在している必要があります。コマンド ラインでファイルの名前を指定します。コマンド ライン引数でサブディレクトリを指定しないでください。

スケジュール済み

cron、launchctl、または Windows タスク スケジューラを使用します。このソフトウェアを実行する場合、有効な環境に適切な環境設定が行われていることを確認し、次のコマンドを実行します: python3 $VCS/vcs2ac your_config_file_name.yml ($VCS は、ソフトウェアがインストールされているディレクトリの完全修飾パスを含む環境変数への参照です)。たとえば、パッケージを /opt/local/sw に解凍した場合、VCS は次のように設定されます: export VCS=/opt/local/sw/vcsconn-2.0.0。

更新

コネクタを再インストールまたは更新する場合は、設定ファイルのコピーを保存しておけば、設定作業をやり直す必要はありません。

時間ファイル

通常の操作では、コネクタは、設定ファイル名に基づいて命名された時間ファイルを(log ディレクトリに)書き込みます。例: 設定ファイル名が product_x.yml の場合、関連する時間ファイル名は product_x_time.file になります。時間ファイルには、人間が解読可能な日付/時刻のタイムスタンプ値を表す 1 行(形式: YYYY-MM-DD hh:mm:ss Z)が含まれています。この値は、Agile Central に反映された最後のコミットのタイムスタンプを表します。コネクタが続いて実行されると、時間ファイルが参照され、開始時間が時間ファイルの値以降であるコミットのみを処理することによって、現在の実行でどのジョブを認識する必要があるかが判断されます。時間ファイルの値は手動で設定できます(2017-05-12 11:37:55 Z など、ISO 形式を使用)。これにより、過去にさかのぼって、過去の任意の時点からコミットを取得できます。コネクタはコミットを複製しないので、Agile Central に重複した情報がポストされることはありません。時間ファイルがない場合、コネクタは、現在の時間より 3 日前の時点からのコミットを取得します。

トラブルシューティング

コネクタは常に、設定ファイル名に基づいて命名されたログ ファイルを書き込みます。ログ ファイルは、ベース インストール ディレクトリの下の log サブディレクトリに書き込まれます。設定ファイル内でレベルを指定すると、ログ記録の範囲を制御できます。設定ファイル内で、ログ ファイルに書き込まれるログ情報の量を決定する LogLevel を設定できます。Service セクションで、LogLevel 設定を変更します(有効な値は、ERROR、WARN、INFO、DEBUG)。LogLevel を DEBUG に設定した場合、完全なログ メッセージを取得できます。これは、問題が発生した箇所を突き止めたり、異常が発生した時点で処理されていた情報を特定したりするのに役に立ちます。

最初の設定では、コネクタをプレビュー モードで実行すると非常に便利です。これにより、変更セットをポストしなくても、Agile Central と VSTS/TFS への接続を確立して、正しく初期化および検証できます。

問題とエラー

 

* 問題: 取得準備リクエストが Agile Central に転送されていません。
回答: 設定ファイル内に以下の行があることを確認します。

PullRequests : True # デフォルトは False です。True の場合、VSTS PullRequests が検出され、Agile Central に反映されます 

* 問題: すべてのリポジトリを取得するために include ステートメントで * を使用している場合にエラーが検出されました。 

FATAL: VCSConnectorRunner.run - VCSConnectorRunner.getConfiguration vcs_connector_runner.py(288) - Unable to parse config/vsts-cloud.yml successfully, while scanning an alias
  in "", line 25, column 26:
                Include   :  *
                             ^
expected alphabetic or numeric character, but found '\n'
  in "", line 25, column 27:
                Include   :  *
                              ^

回答: include ステートメント内の * を引用符でエスケープします。

 Repository:
            Include   : "*"

 

* 問題: VSTS コネクタ バージョン 2.4.0 のログ ファイルにサーバ エラーが表示されています。 

ERROR: VCSConnectorRunner.run - 'Server'

 


回答: この問題は次のリリースで修正されます。この問題を一時的に回避するには、AgileCentral セクションの設定ファイルに以下の行を追加します。 

Server : rally1.rallydev.com

 

 

セキュリティ レベル

設定ファイル内で認証情報がクリア テキストでなくなった場合、SecurityLevel 設定はアップグレードのみが可能で、ダウングレードはできません。たとえば、Encrypted から Encoded への SecurityLevel のリセットでは、暗号化された認証情報が含まれる設定ファイルを使用できません。セキュリティ レベルをダウングレードする場合、認証情報がクリア テキストになっている設定ファイルで開始する必要があります。

付録 A - 設定ファイルの編集

VSTS/TFS 向けの Agile Central vcs2ac コネクタでは、テキスト ファイルを YAML 形式で使用します。詳細については、Web ページや YAML に関するその他の Web サイトを参照してください。説明が含まれる設定ファイルのサンプルについては、このページの下部にある「サンプルのダウンロード」を参照してください

簡潔にするため、このドキュメントでは最も重要ないくつかの構文アイテムを扱い、コネクタで使用できる有効な YAML 設定の 3 つのセクションについて説明しています。

  • ファイルを編集するには、MS Word や Google ドキュメントではなく、テキスト エディタを使用してください。
  • ファイルには、タブ文字を使用しないでください。YAML ではタブ文字が許可されず、認識されません。
  • ファイルは UTF-8 形式で保存します。
  • 等幅フォントを使用します。
  • インデントには同じ数のスペースを使用するようにします。
  • 行では、最初に出現する引用符のない # 文字はコメントであることを示し、# 文字とそれに続くすべての文字は処理の際に無視されます
  • セクションの順序は sample.yml ファイルと同じになるようにします。
  • コロン(:)は重要なので注意してください。コロンによってキーと値が区切られます。
  • ダッシュ(-)も重要です。ダッシュはリストの開始を示し、リストにはリスト アイテムを構成するキーと値のペアが 1 つ以上含まれます。
  • 値にスペースが含まれている場合、通常は値を引用符で囲む必要はありません。# 文字が埋め込まれている場合は、値を引用符で囲む必要があります。


template_config.yml ファイルの構造 

 VCSConnector:
         AgileCentral:
             ...  # いくつかのキーと値のペアはこのセクションに関連します
         VSTS (or TFSGit):
             ...  # いくつかのキーと値のペアはこのセクションに関連します
         Service:
             ...  # コネクタの全体的な処理に関連するいくつかのキーと 
                  # 値のペアは、このセクションに表示されます

AgileCentral セクションでは、Agile Central との接続の取得に使用する値を指定します。VSTS または TFSGit セクションでは、VSTS/TFS との接続の取得に使用する値を指定し、変更セットを Agile Central にポストするために VSTS/TFS のどのリポジトリを処理するかを制御するポリシーを指定します。Service セクションでは、全体的なコネクタ動作の一部の側面を制御します。このコネクタで使用できるすべてのオプションについては、コネクタのメイン インストール ディレクトリにある README_VSTS.txt または README_TFSGIT.txt ファイルを参照してください。

リビジョン履歴

  • 2.0.0-Master --- 2017 年 12 月 21 日
    • VSTS および TFS 2017 をサポートする最初のリリース(Git を使用するプロジェクト向け)

フィードバック

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