CA Agile Central Build Connector for Jenkins インストール & ユーザ ガイド

概要

Jenkins の CA Agile Central ビルド コネクタは、関連性のあるアーティファクトを識別するための十分な情報が VCS コミット メッセージに含まれている場合、Jenkins ジョブ ビルドに関する情報を CA Agile Central にポストし、それらのビルド アイテムを AC 変更セットとアーティファクトに関連付けます。このコネクタは、ディフェクト、ユーザ ストーリー、およびタスクのアーティファクト タイプをサポートします。

CA Agile Central ビルド コネクタは、一方向および 1 回限りのメカニズムとして分類されます。Jenkins 内の情報は変更されません。AC ビルド コネクタは、目的のスケジュールに従ってご使用のプラットフォーム上で実行するソフトウェアで構成されます。コネクタの設定は、ポリシー ベースです。つまり、コネクタの動作の対象となる各ジョブに対して Jenkins 内の設定情報を提供する必要はありません。このコネクタを使用して特定のジョブを設定できますが、シェル正規表現構文を使用するオプションを使用してジョブを含めたり除外したりして、ビューおよびフォルダごとに設定することもできます。ポリシー ベースの性質を使用すると、Jenkins ジョブを追加することができ、それらのジョブのビルドが Agile Central にポストされるように設定を変更する必要はありません。現在、マルチ ブランチ パイプラインのジョブはサポートされていません。

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

ソフトウェア要件

  • Linux、Windows、Mac のプラットフォームがサポートされています。
  • Linux および Mac のプラットフォーム:
    1. Jenkins 2.2 以上(Cloudbees のサポートは保証されませんが、お客様からは Cloudbees でビルド コネクタを問題なく使用していることが報告されています)
    2. Python 3.5 以上。インストーラ パッケージは www.python.org から取得できます。
  • Windows プラットフォーム:
    1. Jenkins 2.2 以上(Cloudbees のサポートは保証されませんが、お客様からは Cloudbees でビルド コネクタを問題なく使用していることが報告されています)
    2. Python 3.5 以上 - 64 ビット バージョンを使用することをお勧めします。インストーラ パッケージは www.python.org から取得できます。
    3. win32com モジュール - SourceForge から入手可能(ここから)。64 ビット版の Python3.5.x 以上を使用している場合、SourceForge の Python for Windows Extensions リストから適切なファイルを取得してください。

コネクタのダウンロード

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

インストール

Jenkins と Python がインストールされ、(Windows ユーザの場合のみ) win32com モジュールがインストールされたら(前述の情報は「ソフトウェア要件」セクションを参照)、以下の Python パッケージをインストールします:

  1. pip3.5 install requests==2.8.1
  2. pip3.5 install pyral==1.2.3
  3. pip3.5 install PyYAML==3.12
  4. cd コマンドを使用して、作業ディレクトリを、コネクタをインストールするディレクトリに変更します
  5. bldeif-1.0.0.zip を解凍します(または .zip ファイルを解凍できる適切なプログラムを使用)
  6. cd bldeif-1.0.0
  7. ls -laR # 解凍されたコンテンツを確認するか、Windows で dir を使用します

サンプル コンテンツ

bldeif            # bldeif モジュールのルート ディレクトリ
bldeif_connector  # コネクタ起動スクリプト(これが実行するファイルになります)
config            # このコネクタで使用する設定ファイルを保持
sample.yml        # 参照の基準として使用するサンプル設定ファイル
README.txt        # このファイル

セットアップ

CA Agile Central のセットアップ

ターゲット WorkspaceConfiguration オブジェクトに対して BuildandChangsetEnabled が true に設定されていることを確認します。

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

ワークスペースの管理者は、ワークスペースを編集して、以下のことを実行する必要があります。

  1. セットアップ]アイコン をクリックします。
  2. ワークスペースとプロジェクト]タブをクリックします。
  3. [ワークスペースとプロジェクト]サマリ ページで、ワークスペースを選択します。
  4. [アクション]ドロップダウンから[編集]を選択します。
  5. ワークスペース エディタで、[ビルドと変更セットを有効化]というラベルが付いたチェック ボックスをオンにします。
  6. 保存して閉じる]をクリックします。

 

セットアップ:

  1. config サブディレクトリを見つけます。
  2. sample.yml ファイルを、環境に合わせて名前が付けられたファイルにコピーします。たとえば cp sample.yml から product_x.yml などです(または他の適切な名前が付けられた拡張子が .yml のファイル)。
  3. product_x.yml ファイルを編集します。
  4. 認証情報、ワークスペース、プロジェクト、ジョブ、ビュー、フォルダのサンプル値を、環境に有効で関連する値に変更します。

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

Jenkins のセットアップ

Jenkins のユーザ ID は[Manage Jenkins]ページにアクセスする必要があります(管理者権限)。

操作

手動

ターミナル ウィンドウまたはコンソールを使用して次の操作を実行します: cd コマンドでインストールのルート ディレクトリ(たとえば /opt/local/sw/bldeif-1.0.0)に移動し、次のコマンドを実行して product_x.yml を該当する .yml ファイルの名前に置き換えます: python3.5 bldeif_connector product_x.yml (Windows の場合、このコマンドは次のようになる可能性があります: python bldeif_connector your_configfile.yml)。このソフトウェアでは、設定ファイルが config サブディレクトリに存在している必要があります。コマンド ラインではファイルの名前を指定します(コマンド ライン引数でサブディレクトリを指定しないでください)。

スケジュール済み

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

時間ファイル

通常の動作では、コネクタは、設定ファイル名に基づいて命名されたログ ディレクトリに時間ファイルを書き込みます。

例: 設定ファイル名が product_x.yml の場合、関連する時間ファイル名は product_x_time.file になります。時間ファイルには、人間が解読可能な日時のタイムスタンプ値が 1 行で含まれています(形式: YYYY-MM-DD hh:mm:ss Z)。この値は、認識された最新の Jenkins ジョブのタイムスタンプを表します(その前に Jenkins ジョブの見落としがないように負の値の調整が行われています)。コネクタが続いて実行されると、時間ファイルが参照され、開始時間が時間ファイルの値と等しいかそれ以降であるビルドのみを処理することによって、現在の実行に対してどのジョブを認識する必要があるかが判断されます。時間ファイルの値を作為的に設定することもできます(ただし正しい形式で)。そうすることにより、ビルドを過去のある時点にさかのぼって処理することができます。コネクタはビルド レコードを複製しないため、重複する情報が Agile Central にポストされることはありません。

コネクタに関連するサンプル シナリオ

  1. リポジトリにコミットします(Jenkins ジョブに設定されているのと同じリポジトリ)。これは、Rally サービスと GitHub を使用して変更セットを Agile Central にプッシュする場合も同様に動作します。(注: このシナリオでは、GitHub は情報を Jenkins にもプッシュする必要があります。) Bitbucket リポジトリを使用する場合、リポジトリは Git リポジトリとして複製される必要があります(現時点では、コネクタは Bitbucket からデータを読み取ることができません)。コミットでは、メッセージ内で Rally アーティファクトを参照する必要があります。例: git commit -m "test for DE82 fixes"
  2. 手順 1 の Git リポジトリに対して VCS コネクタを実行します(例: Git または SVN)(GitHub を使用している場合は不要)。
  3. Agile Central で、変更セットが手順 1 のコミット メッセージに記載されているアーティファクトに追加されたことを確認します(例では DE82)。
  4. 手順 1 の Git (または GitHub)リポジトリに接続されている Jenkins ジョブを実行します。
  5. インストール ルート ディレクトリから Jenkins のビルド コネクタを次のコマンドで実行します: python3.5 bldeif_connector your_configfile.yml (Windows では、このコマンドは次のようになる可能性があります: python bldeif_connector your_configfile.yml)
  6. Agile Central で、ビルド情報が手順 3 の変更セットに追加されたことを確認します。ビルド情報は、Agile Central ダッシュボード上でビルド アプリの 1 つを介して参照することもできます([ビルドのトレーサビリティ]または[ビルドのヘルス]など)。

トラブルシューティング

コネクタは、常に設定ファイル名に基づいてログ ファイル名を書き込みます。ログ ファイルは、ベース インストール ディレクトリの下の log サブディレクトリに書き込まれます。設定ファイル内で、ログ ファイルに書き込まれるログ情報の量を決定する LogLevel を設定できます。LogLevel を DEBUG に設定した場合、完全なログ メッセージを取得できます。これは、問題が発生した箇所を突き止めたり、異常が発生した時点で処理されていた情報を特定したりするのに非常に役に立ちます。

最初の設定では、コネクタをプレビュー モードで実行すると非常に便利です。これにより、ビルド情報をポストしなくても、Agile Central と Jenkins への接続が確立され、正しく初期化および検証することができます。このモードでは、ビルド情報を Agile Central に実際にポストせずに、どの Jenkins ジョブが実際に処理されるのかを表示することもできます。

*問題: win32com モジュールがインストールされていない場合、以下のエラーが発生します。

C:\Connectors\bldeif-1.1.3>python ac_build_connector sample_jenkins.yml
ERROR: ac_build_connector encountered an ERROR condition.
  File "ac_build_connector", line 31, in main
    connector_runner.run()
  File "C:\Connectors\bldeif-1.1.3\bldeif\bld_connector_runner.py", line 137, in run
    self.proclaim_existence(build_system_name)
  File "C:\Connectors\bldeif-1.1.3\bldeif\bld_connector_runner.py", line 103, in proclaim_existence
    proc = ProcTable.targetProcess(os.getpid())
  File "C:\Connectors\bldeif-1.1.3\bldeif\utils\proctbl.py", line 96, in targetProcess
    aps = ProcTable.allProcesses()
  File "C:\Connectors\bldeif-1.1.3\bldeif\utils\proctbl.py", line 29, in allProcesses
    all_procs = ProcTable.posixProcesses()
  File "C:\Connectors\bldeif-1.1.3\bldeif\utils\proctbl.py", line 44, in posixProcesses
    ps_output = subprocess.Popen(command_vector, stdout=subprocess.PIPE).communicate()[0]
  File "C:\Users\user01\AppData\Local\Programs\Python\Python36\lib\subprocess.py", line 709, in __init__
    restore_signals, start_new_session)
  File "C:\Users\user01\AppData\Local\Programs\Python\Python36\lib\subprocess.py", line 997, in _execute_child
    startupinfo)
FileNotFoundError: [WinError 2] 指定されたファイルが見つかりません

回答: win32com モジュールをインストールします。インストール手順については、本書の「ソフトウェア要件」を参照してください。

 

*問題: ログ ファイルが生成される前にコネクタを実行すると画面に以下のエラーが表示されます。

C:\Users\tester\bldeif-1.1.3>python ac_build_connector test1.yml 
ERROR: ac_build_connector encountered an ERROR condition. 
File "ac_build_connector", line 31, in main connector_runner.run() 
File "C:\Users\tester\bldeif-1.1.3\bldeif\bld_connector_runner.py", line 137, in run 
self.proclaim_existence(build_system_name) 
File "C:\Users\tester\bldeif-1.1.3\bldeif\bld_connector_runner.py", line 103, in proclaim_existence 
proc = ProcTable.targetProcess(os.getpid()) 
File "C:\Users\tester\bldeif-1.1.3\bldeif\utils\proctbl.py", line 96, in targetProcess 
aps = ProcTable.allProcesses() 
File "C:\Users\tester\bldeif-1.1.3\bldeif\utils\proctbl.py", line 29, in allProcesses 
all_procs = ProcTable.posixProcesses() 
File "C:\Users\tester\bldeif-1.1.3\bldeif\utils\proctbl.py", line 47, in posixProcesses 
cmd_column_ix = hdr_line.index('CMD') 
ValueError: substring not found

回答: win32com モジュールのバージョンが python のバージョンに一致していません(例: python 3.5 用の win32com モジュールがインストールされているが、システムで実行されているバージョンが python 3.6 である場合など)。インストール手順については、「ソフトウェア要件」を参照してください。

既知の制限

BuildDefinition の名前と URL

AgileCentral 内には、BuildDefinition というエンティティがあり、Jenkins 用のビルド コネクタに対する Jenkins ジョブの名前が含まれます。BuildDefinition アイテムに記録される Jenkins ジョブは、フォルダおよびビューの要素を含むジョブの完全な URL です。BuildDefinition 名の文字数の上限は 256 文字です。Jenkins ジョブの URL の長さが 256 文字を超えている場合、コネクタではジョブ URL の先頭の文字を削除して、URL の長さが 256 文字を超えないようにします。この文字列値が BuildDefinition 名として使用されます。一部のエッジ ケースでは、Jenkins のインストールで複数の Jenkins ジョブの完全 URL に対してこの種の修正が発生する場合があり、結果として同じ省略値が生成される可能性があります。これは頻繁に発生するとは思われません。Jenkins インストールのフォルダとビューの名前がかなり長く(1 つのフォルダ名またはビュー名が 40 文字を超える)、ネスティングのレベルが多い(6 レベルを超える)場合、コネクタの設定ファイルを変更して、ジョブの URL が 256 文字を超える場合に設定ファイルに指定されないようにする必要がある可能性があります。

Jenkins ジョブ URL の例:

    http://bigjenkins.stegasaurus.ancient:8080/job/ReallyLongScientificFolderName/.../job/FernCoveredLowlands/job/MickyDinosaur

結果

    .../job/FernCoveredLowlands/job/MickDinosaur

名前が重複するジョブまたはフォルダ/ビューをコネクタが処理する方法

「付録 B」を参照してください。

VCS のサポート

  • 現在、関連するジョブが Git リポジトリを使用している限り、コネクタはビルドに関連する変更セットを処理します。
  • Subversion を含む設定で正常に動作するものもありますが、Jenkins バージョン、Subversion バージョン Jenkins Subversion プラグイン バージョンの組み合わせのうち、ビルド情報に対して返される json データとの差異によりコネクタでは機能しないものがあります。
  • Subversion に対して指定された VCS コネクタと、Jenkins コネクタを共に使用してコミット/変更セットおよびビルド情報をキャプチャすることをお勧めします。その場合、Jenkins 設定ファイルで ShowVCSData プロパティを False に設定します。

付録 A - 設定ファイルの編集(ノート)

Jenkins の CA Agile Central bldeif コネクタは、テキスト ファイルを YAML 形式で使用します。詳細については、www.yaml.org/start.html または YAML に関する他の多くの Web サイトを参照してください。

このドキュメントでは、最も関連する構文項目のいくつかを扱い、コネクタで使用できる有効な YAML 設定の 3 つのセクションについて説明しています。

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


Sample_config.yml のスケルトン 

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

 

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

説明的な表記を含むサンプル ファイル:

---------------------------------------------
 
JenkinsBuildConnector:
     AgileCentral:   # 使用可能なキーと値のペアのすべて。すべてを使用する必要はありません。右側を参照してください
                     # 必須の場合は 'R'、任意の場合は 'O' を指定することをコメント
         Server:       : rally1.rallydev.com      # R
         Username      : [email protected]  # R   APIKey エントリが使用される場合は必要ありません
         Password      : 2MuchAngst1415           # R   APIKey エントリが使用される場合は必要ありません
         APIKey       : _zzzyyyy234twqwtqwet89y4t38g38y0  # O Username と Password の代わりにこれを使用できます
         ProxyServer   : wu-tank.smooth.org       # O
         ProxyUser     : jessonbrone              # O
         ProxyPassword : S-e-c*r*ET321!789       # 0
         Workspace     : My Onliest Workspace     # R  SCMRepository、変更セットおよびビルドのレコードが
                                                  # 書き込まれる Agile Central ワークスペースの名前

     Jenkins:   # 使用可能なキーと値のペアのすべて。すべてを使用する必要はありません。右側を参照してください
                     # 必須の場合は 'R'、任意の場合は 'O' を指定することをコメント
         Protocol    : http                       # R
         Server      : jenkado.mydomain.com       # R
         Port        : 8080                       # R
         Prefix      :                            # O  (標準以外のディレクトリを使用するカスタムの Jenkins インストールの場合)
         Username    : validuser                  # R  Jenkins でアクセスのための認証情報が必要とされる場合に値を指定します
         Password    : somepasswd                 # R  Jenkins でアクセスのための認証情報が必要とされる場合に値を指定します
         API_Token   : 320ca9ae9408d099183aa052ff3199c2  # O 認証情報が必要な場合に Password の代わりに使用できます
         MaxDepth    : 3                          # O  認識されるフォルダ レベルの数(デフォルトは 3)
                                                  #    AlphaFolder // BetaFolder // CherryFolder と、そのフォルダ内にジョブがあるような状況にも対応します
         AgileCentral_DefaultProject : Agile Central プロジェクト名  # R

         Folders:
             - Folder: フォルダ名
               include: toaster,microwave,stove  # O 指定されたジョブのみが含まれるように 
                                                 # 含めるジョブ名の明確なパターンを指定します。この例では以下のジョブが含まれます
                                                 #   stove-hot、stove-warm、stove-burning
             - Folder: 別のフォルダ名
               exclude: beta-,post-prod      # O 除外するジョブ名の明確なパターンを指定します。
                                             # 完全なジョブ名を指定する必要はありません
               AgileCentral_Project: Divison X // National // Engineering

         Views:
             - View  : ビュー名
               AgileCentral_Project: Divison Y // Provincial // Engineering
             - View  : 別の名前
               include: prod-
               exclude: pre-prod

         Jobs:
             - Job   : ジョブ名
               AgileCentral_Project: Beta Test for Northeast
             - Job   : 別のジョブ名     # このジョブは一意の名前を持ち、最上位レベル以外のビューまたはフォルダ内に存在します

     Service:
         Preview      : True   # True に設定した場合、コネクタは処理されるアイテムを表示しますが
                               # ビルド情報を実際に Agile Central にポストしません
                               # セットアップが完了し、AgileCentral および Jenkins との接続が正常に確立されたら、
                               # この値を True に変更できます
         LogLevel     : INFO   # これはデフォルト値です。DEBUG、WARN、ERROR に変更することもできます。DEBUG の場合は非常に詳細に記録されます
         MaxBuilds    : 100    # 負でない整数を使用します。この制限は、特定のジョブのビルドに関連します。

 ------  ファイルの終わり ---------------------------------------

: このコネクタを実行するには、Jenkins セクションの設定フィールドに Jenkins 管理者のユーザ名とパスワードを使用する必要があります。

付録 B - Jenkins での名前の重複の処理

コネクタは指定されたフォルダ内のジョブを処理しますが、上位レベルのフォルダを指定して、そのフォルダ内のすべてのジョブおよびネストされているレベル内のフォルダに含まれているすべてのジョブを直接処理する機能はありません。フォルダ内のジョブが処理されるようにするには、そのフォルダ名を設定ファイルに指定する必要があります。

以下のように、ネストされたフォルダ構造が存在する場合があります:
      - 上位フォルダ
        -- ジョブ 1
        -- 下位フォルダ
           -- ジョブ 2

ジョブ 1 とジョブ 2 の両方がコネクタによって処理対象として認識されるようにするには、設定ファイルの Folders セクションに以下のように指定する必要があります:
         Folders:
           - Folder : 上位フォルダ
           - Folder : 下位フォルダ

Jenkins ジョブの編成において、同じ名前で複数の場所に複数のフォルダが存在する場合、
      完全修飾パスを使用して各フォルダを指定する必要があります。その際、フォルダ/ビューのレベルごとに // をセパレータとして使用します。
        設定ファイルの例:
            Jenkins:
                ...
                MaxDepth : 5
                FullFolderPath : True
                ...
                Folders:
                    - Folder: Area 51 // Intermediate Stuff // Good Stuff
                    - Folder: Level1 // Level 2 // Level 3 // Good Stuff


付録 C: AgileCentral プロジェクト仕様


    AgileCentral では、プロジェクト名は一意である必要はありません。コネクタは、同じ名前のプロジェクトを識別する仕組みを提供しています。
    たとえば、プロジェクト ツリーの一部が以下のようになっているとします。

    |__ Jenkins
        |__ Salamandra
        |__ Corral
            |__ Salamandra

   ビルド定義が AC で正しいプロジェクトに割り当てられるようにするには、以下の構文を使用する必要があります。


     設定ファイルの例:

       Jenkins:
           ...
           AgileCentral_DefaultBuildProject : Jenkins

           Jobs:
               - Job: monitor sub-tropical habitat
                 AgileCentral_Project: Jenkins // Salamandra
               - Job: fill the water bottles
                 AgileCentral_Project: Jenkins // Corral // Salamandra

 

サポートされているバージョン

バージョン サポートの終了
Jenkins 2.2 以上 N/A

リビジョン履歴

  • 1.1.3-Master --- 2017 年 10 月 20 日
    • 修正点
      • 更新されたタイムスタンプ関数の問題
  • 1.1.2-Master --- 2017 年 3 月
    • 初期リリース

フィードバック

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