GitHub および GitHub Enterprise 用 CA Agile Central VCS コネクタ

概要

GitHub および GitHub Enterprise (GHE)用 CA Agile Central VCS コネクタは、GitHub リポジトリのコミットに関する情報を Agile Central (AC)にポストし、関連するアーティファクトを特定するのに十分な情報が VCS コミット メッセージに含まれている場合、これらのコミット内容を AC の変更セットおよびアーティファクトに関連付けます。

例:

"Fixed DE1987 by changing preamble paragraph 3"

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

コミット メッセージには、複数のアーティファクトへの参照を含めることができます。たとえば、以下は正常に機能します。

"Test commit msg with multiple artifacts Fixed DE9 Closed DE8"

コネクタでは取得準備リクエストがサポートされています。取得準備リクエストを Agile Central にサードパーティ コンテキストとして表示するには、PullRequests 値を True に設定します。AC アーティファクトのフォーマット済み ID (例: US1234)は、コネクタで処理するために、取得準備リクエストのタイトルまたは取得準備リクエストに関連付けられているいずれかのコミット メッセージに記述できます。コネクタには、オープンされている取得準備リクエストとマージされた取得準備リクエストが含まれます。

GitHub 用 Agile Central VCS コネクタは、一方向および 1 回限りのメカニズムに分類されます。GitHub の情報は変更されません。情報は Agile Central に書き込まれるだけで、データの複製が試行されたり許可されたりすることはありません。GitHub 用 Agile Central VCS コネクタは、必要なスケジュールに従ってご使用のプラットフォーム上で実行するソフトウェアで構成されています。コネクタの設定はポリシーベースです。つまり、コネクタの動作対象となる GitHub リポジトリごとに個別の設定ファイルを指定する必要はありません。ポリシーベースの特徴により、GitHub のユーザや組織がアクセス可能なリポジトリのすべてまたは一部を対象にすることができます。コネクタは、コミット用のマスタ ブランチだけを検索します。

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

ソフトウェア要件

コネクタのダウンロード

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

ハードウェア

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

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

インストール

  1. 注: ご使用の環境で Python 3.5.x または 3.6.x が利用可能である必要があります。
  2. ZIP ファイルを解凍します。
    cd MyInstallDir # change your working directory to where you want to install the connector
    unzip vcsconn-2.0.3.zip  #  or use a suitable program to unzip the file
    cd vcsconn-2.0.3
    ls -laR # 解凍されたコンテンツを確認します。Windows では dir を使用します
            #       ghconn                  # ghconn module root directory
            #       vcs2ac                  # connector initiation script, this is what you will run
            #       configs                 # holds any config files used with this connector
            #       sample.yml              # a sample config to use as a base reference
            #       sample_user_map.txt     # a sample text file for user mapping
            #       logs                    # hold log file and time file per configuration
            #       README.txt              # installation and users guide

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

    セットアップ

    1. CA Agile Central のセットアップ:
      • ターゲット WorkspaceConfiguration オブジェクトに対して BuildandChangsetEnabled が true に設定されていることを確認します。
      • そうでない場合、CA Agile Central ワークスペースの管理者は、ターゲット ワークスペースに対してこれを有効にする必要があります。これが有効でない場合は、コネクタは機能しますが、Agile Central 作業アイテム(ストーリー、ディフェクト、タスク)に関連付けられている変更セットまたは変更の情報は表示されません。
      • このオプションを有効にするには、ワークスペースの管理者はワークスペースを編集して、以下のことを実行する必要があります。
        • セットアップ]アイコン をクリックします。
        • ワークスペースとプロジェクト]タブをクリックします。
        • [ワークスペースとプロジェクト]サマリ ページで、ワークスペースを選択します。
        • [アクション]ドロップダウンから[編集]を選択します。
        • ワークスペース エディタで、[ビルドと変更セットを有効化]というラベルが付いたチェック ボックスをオンにします。
        • 保存して閉じる]をクリックします。
    2. 設定ファイルをセットアップします。
      • config サブディレクトリを見つけます。
      • Copy the sample.yml ファイルを、環境に合わせて名前が付けられたファイルにコピーします(たとえば、「sample.yml から product_x.yml へコピー」。または、適切な名前が付けられた拡張子 .yml のその他のファイル)。
      • product_x.yml ファイルを編集します。
      • 認証情報、ワークスペース、プロジェクト、ジョブ、ビュー、フォルダのサンプル値を、環境に有効で関連する値に変更します。
      • 設定ファイルの構文については、「付録 A」を参照してください。

    設定

    github_connector の設定は、設定サブディレクトリ内にある YAML ファイルを介して実行されます。設定サブディレクトリ内には、テンプレートとして使用できる sample.yml という名前のサンプル設定ファイルがあります。用途や環境を反映した名前のファイルにコピーし、このファイルを編集して、状況に関連する値に置換します。

    一般的な推奨事項

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

    2. configuration サブディレクトリを見つけます。

    3. sample.yml ファイルを環境に合わせて名前が付けられたファイルにコピーします。たとえば、sample.yml から acdata.yml にコピーします。

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

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

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

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

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

    操作

    手動

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

    スケジュール済み

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

    時間ファイル

    通常の操作では、コネクタは、設定ファイル名に基づいて命名された時間ファイルを(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 日前の時点からのコミットを取得します。

    拡張

    別の SaaS VCS をサポートするには、ご使用のビルド システム用に、getOrganizations への呼び出しおよび getRecentRepositoryActivity(ref_timestamp) をサポートできる接続スポークを開発する必要があります。その方法はコミット アイテムのリストを返す必要があります。コミット アイテムには以下の属性があります。

    • SHA
    • タイムスタンプ
    • 作成者
    • メッセージ
    • 変更

    トラブルシューティング

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

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

    * 問題: 取得準備リクエストが 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   : "*"

    セキュリティ レベル

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

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

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

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

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


    template_config.yml ファイルの構造

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

    AgileCentral セクションでは、Agile Central との接続の取得に使用する値を指定します。GitHub セクションでは、GitHub との接続の取得に使用する値を指定し、変更セットを Agile Central にポストするために GitHub のどのリポジトリを処理するかを制御するポリシーを指定します。設定ファイルの GitHub セクションで、GitHub Enterprise のサーバを指定する必要があります。Service セクションでは、全体的なコネクタ動作の一部の側面を制御します。たとえば、このセクションに取得準備リクエストを True として追加できます。

    リビジョン履歴

    • 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.0-Master --- 2017 年 11 月 28 日
      • 取得準備リクエストのサポートが追加されました
    • 1.2.2-Master --- 2017 年 10 月 16 日
      • フォーマット済み ID に対して解析される取得準備リクエストのタイトルが含まれました
    • 1.1.1-Master --- 2017 年 9 月 12 日
      • バージョン 2.10.0 より GitHub Enterprise (GHE)のサポートが追加されました
    • 1.0.0-Master --- 2017 年 5 月 30 日
      • 初期リリース
    サンプルをダウンロード

    フィードバック

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