CA Agile Central

Bitbucket 向け VCS コネクタ

概要

Bitbucket サーバおよび Bitbucket クラウド向けの CA Agile Central VCS コネクタは、Bitbucket リポジトリのコミットに関する情報を CA Agile Central にポストし、関連するアーティファクトを特定するのに十分な情報が VCS コミットメッセージに含まれている場合、これらのコミット内容を CA Agile Central の変更セットおよびアーティファクトに関連付けます。また、このコネクタは、コミットメッセージに適切な構文（たとえば、「US123 進行中」）が含まれている場合、関連する CA Agile Central アーティファクトの状態（具体的には、ディフェクトの状態やユーザストーリーのスケジュール状態）を更新します。Bitbucket 向けの CA Agile Central VCS コネクタは、一方向および 1 回限りのメカニズムに分類されます。Bitbucket の情報は変更されません。情報は Agile Central に書き込まれるだけで、データの複製が試行されたり許可されたりすることはありません。Bitbucket 向けの CA Agile Central VCS コネクタは、必要なスケジュールに従ってご使用のプラットフォーム上で実行するソフトウェアで構成されています。コネクタの設定はポリシーベースです。つまり、コネクタの動作対象となる Bitbucket リポジトリごとに個別の設定ファイルを指定する必要はありません。ポリシーベースの特徴により、Bitbucket のユーザや組織がアクセス可能なリポジトリのすべてまたは一部を対象にすることができます。

現在のバージョン 2.0.3 の Agile Central VCS コネクタには、設定オプションがターゲットの設定ファイルに存在する場合に、Bitbucket の取得準備リクエストのアイテムの作成を検出し、Agile Central の対応する取得準備リクエストのアイテムをポストする機能が含まれています。現在、取得準備リクエストの機能はユーザストーリーでのみ利用可能です。取得準備リクエストを Agile Central にサードパーティコンテキストとして表示するには、PullRequests 値を True に設定します。AC アーティファクトのフォーマット済み ID （例： US1234）は、コネクタで処理されるために、取得準備リクエストのタイトルまたは取得準備リクエストに関連付けられているコミットメッセージの 1 つのいずれかに記述できます。コネクタには、オープンされている取得準備リクエストとマージされた取得準備リクエストが含まれます。

このコネクタは Bitbucket REST API を使用しているため、Bitbucket サーバおよび Bitbucket クラウドの両方で動作します。Bitbucket サーバと Bitbucket クラウドのどちらを使用しているかによって、設定ファイルのアイテムはわずかに異なります。

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

ソフトウェア要件
コネクタのダウンロード
インストール
ハードウェア
セットアップ
操作
トラブルシューティング
付録 A
リビジョン履歴

ソフトウェア要件

CA Agile Central の有効なサブスクリプションと認証情報。
アクティブな Bitbucket アカウント。Bitbucket バージョン 5.0、5.1、および 5.2 がサポートされています。その他の 5.x バージョンでも動作する可能性があります。
Python 3.5.x または 3.6.x （3.6.x が推奨されます。Windows ユーザの場合、64 ビットバージョンの使用を推奨します）。パッケージ/インストーラは、www.python.org から取得できます。
Windows のみの追加の要件
- pywin32 パッケージは、Python 3.5 または 3.6 のインストール後にダウンロードしてインストールする必要があります。
- pywin32 パッケージは次の場所から入手できます： https://sourceforge.net/projects/pywin32/files/pywin32/Build%20221/pywin32-221.win-amd64-py3.5.exe/download および https://sourceforge.net/projects/pywin32/files/pywin32/Build%20221/pywin32-221.win-amd64-py3.6.exe/download

コネクタのダウンロード

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

ハードウェア

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

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

インストール

** 設定のサンプルファイルと、このコネクタで利用可能なすべてのオプションを参照するには、このドキュメントの一番下（「ダウンロード」）に移動してください。このファイルの名前は「sample file with explanatory notations.txt」です。

注：ご使用の環境で Python 3.5.x または 3.6.x が利用可能である必要があります。

以下のコマンドを実行します。

pip3 install requests==2.18.4
pip3 install pyral==1.4.0
pip3 install PyYAML==3.12
pip3 install cryptography==1.7.1

vcsconn-2.0.3.zip を解凍します。cd コマンドを使用して、作業ディレクトリを、コネクタをインストールするディレクトリに変更します vcsconn-2.0.3.zip を解凍します（または .zip ファイルを解凍できる適切なプログラムを使用します）。

    cd vcsconn-2.0.3
    ls -laR # 解凍されたコンテンツを確認します。Windows では dir を使用します

     vcsconn                       # vcsconn モジュールのルート ディレクトリ
     vcs2ac                        # コネクタ起動スクリプト。これが実行するファイルになります
     config                        # このコネクタで使用する設定ファイルを保持します
        sample_bitbucket_server.yml# Bitbucket サーバの基本リファレンスとして使用するサンプル設定
        sample_bitbucket_cloud.yml # Bitbucket クラウドの基本リファレンスとして使用するサンプル設定
        sample_user_map.yml        # ユーザ マッピングのサンプル テキスト ファイル
     log                           # 設定ごとにログ ファイルと時間ファイルを保持します
     README_BITBUCKET.txt          # このファイル
     User-Mapping-Strategies.txt   # Bitbucket ユーザと AgileCentral ユーザ名のマッピング戦略の詳細

セットアップ

一般的な推奨事項

シンプルに開始します。
configuration サブディレクトリを見つけます。
sample_bitbucket_(server または cloud).yml ファイルを、環境に合わせて名前が付けられたファイルにコピーします。たとえば、cp sample_bitbucket_server.yml to product_x.yml （または他の適切な名前が付けられた、拡張子が .yml のファイル）となります。
product_x.yml ファイルを編集します。たとえば、認証情報、ワークスペース、プロジェクト、トークンなどのサンプル値を、ご使用の環境に適した有効な値に変更します。
適切な SecurityLevel を決定します。
コミットメッセージに基づいて CA Agile Central アーティファクトの状態を更新するかどうかを決定します。
Bitbucket コミッタを有効な Agile Central ユーザにマップするかどうかを決定し、Passthrough、FileBasedUserNameLookup、または UserNameDomainAugmentLookup の 3 つのマッピング方法のいずれかを選択します。
処理するリポジトリが、自分が所有するリポジトリであるか（UserSlug を使用）、自分がメンバであるチームが所有するリポジトリであるか（TeamSlug を使用）を決定します。

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

操作

手動

ターミナルウィンドウまたはコンソールを使用： cd コマンドでインストールのルートディレクトリに移動します（たとえば、/opt/local/sw/vcsconn-1.2.4）。その後、以下のコマンドを実行します。

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-1.2.4

時間ファイル

通常の操作では、コネクタは、設定ファイル名に基づいて命名された時間ファイルを（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 と Bitbucket への接続を確立して、正しく初期化および検証できます。

* 問題：取得準備リクエストが Agile Central に転送されていません。
回答：現時点では、取得準備リクエストの機能は Agile Central 内のユーザストーリーでのみ使用できます。ユーザストーリーに取得準備リクエストが表示されていない場合は、設定ファイルの Service セクションに以下の行があることを確認してください。

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   : "*"

セキュリティレベル

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

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

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

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

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

template_config.yml ファイルの構造

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

AgileCentral セクションでは、Agile Central との接続の取得に使用する値を指定します。Bitbucket セクションでは、Bitbucket との接続の取得に使用する値を指定し、変更セットを Agile Central にポストするために Bitbucket のどのリポジトリを処理するかを制御するポリシーを指定します。Service セクションでは、全体的なコネクタ動作の一部の側面を制御します。

* CA Agile Central セクションで必要な Project 行は接続目的で使用されます。コミットは引き続きワークスペーススコープに基づいて CA Agile Central に表示されます。

リビジョン履歴

2.0.3-Master --- 2018 年 2 月 9 日
- サンプル設定ファイル内の StateExtractor クラスの名前が修正されました
- Bitbucket サーバに対する変更セット URI の割り当てが修正されました
2.0.0-Master --- 2017 年 12 月 21 日
- すべての新しいポリシーベースの VCS コネクタが 1 つの配布パッケージに統合されました
1.3.2-Master --- 2017 年 12 月 7 日
- 取得準備リクエストのサポートが追加されました
1.3.1-Master --- 2017 年 12 月 4 日
- Bitbucket サーバで作成者からコミッタへの移行が行われました
- コミットメッセージにコミッタの名前を追加するためのサポートが追加されました
1.2.4-Master --- 2017 年 11 月 17 日
- コネクタが Python で書き直されました
- ポリシーベースのフィーチャーが追加されました
- Bitbucket クラウドのサポートが追加されました

サンプルをダウンロード

sample file with explanatory notations.txt bytes

フィードバック

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