トリガオプション

Swarmトリガスクリプトのswarm-trigger.plには、以下に示すコマンドラインオプションと設定項目が用意されています。

コマンドラインオプション

概要

swarm-trigger.pl -t type -v ID [-c config_file]
swarm-trigger.pl -o
swarm-trigger.pl -h

情報提供オプション

以下のオプションは、Swarmの管理者にとって役立つ情報を提供するためのオプションで、何らかの処理を実行するためのオプションではありません。Helixサーバのトリガエントリ内でこれらのオプションを使用することはできません。

  • -h

    使用可能なオプションの一覧とその使用法に関するガイド情報、現在のパス内のスクリプトを実行するためにHelixサーバで設定する必要のあるトリガテーブルエントリのコピーが表示されます。

  • -o

    現在のパス内のスクリプトを実行するためにHelixサーバで設定する必要のあるトリガテーブルエントリのコピーが表示されます。

操作オプション

Swarmトリガスクリプトの実行方法を指定するには、Helixサーバのトリガテーブルエントリで以下のコマンドラインオプションを使用します。

  • -t type

    トリガスクリプトで実行する処理のタイプを指定します。typeには以下のいずれかを指定します。

    • job: このタイプは、ジョブフォーム用のHelixサーバ form-commitイベントで使用します。ジョブの作成時と変更時に、Swarmに通知されます。
    • user: このタイプは、ユーザフォーム用のHelixサーバ form-commitイベントで使用します。ユーザの追加時と変更時に、Swarmに通知されます。
    • userdel: このタイプは、ユーザフォーム用のHelixサーバ form-deleteイベントで使用します。ユーザの削除時に、Swarmに通知されます。
    • group: このタイプは、グループフォーム用のHelixサーバ form-commitイベントで使用します。グループの作成時と変更時に、Swarmに通知されます。
    • groupdel: このタイプは、グループフォーム用のHelixサーバ form-deleteイベントで使用します。グループの削除時に、Swarmに通知されます。
    • changesave: このタイプは、チェンジフォーム用のHelixサーバ form-saveイベントで使用します。チェンジリストの作成時と変更時に、Swarmに通知されます。
    • shelve: このタイプは、Helixサーバ shelve-commitイベントで使用します。チェンジリストの保留時に、Swarmに通知されます。その際、レビューが作成または更新される場合があります。
    • commit: このタイプは、Helixサーバ change-commitイベントで使用します。チェンジリストのコミット時に、Swarmに通知されます。
    • shelvedel: このタイプは、Helixサーバ shelve-deleteイベントで使用します。ファイルをシェルフから削除すると、Swarmに通知されます。

      • 重要

      シェルフを削除する場合や、シェルフからファイルを削除する場合は、Swarm構成ファイル内で指定されているSwarmユーザを使用しないでください。shelve-deleteトリガイベントが却下されたSwarmユーザがこのイベントを呼び出すと、Swarmロジックによってこのイベントが処理されます。この場合、削除操作が失敗します。

    • enforce: ワークフロー機能が有効になっている場合(ワークフロー機能はデフォルトで有効になっています)、このタイプをコメント化してください。このタイプは、特定のディポパスのコミットが承認済みレビューに関連付けられているかどうかを確認する場合に使用します。指定したディポパス内のファイルがコミット対象であり、コミットがレビュー(または未承認のレビュー)に関連付けられていない場合、そのコミットは却下されます。

      • enforceタイプを使用すると、特定のディポパスに対する変更がレビューも承認もされていない場合、ユーザはその変更をコミットできなくなります。

    • strict: ワークフロー機能が有効になっている場合(ワークフロー機能はデフォルトで有効になっています)、このタイプをコメント化してください。このタイプは、コミット対象のファイルの内容が、関連する承認済みレビューのファイルの内容と一致しているかどうかを確認する場合に使用します。コミット対象の1つ以上のファイルが、関連付けられているレビューの対象ファイルの内容と一致しない場合は、コミットが却下されます。

      • strictタイプを使用すると、レビューの承認後にファイルの内容を変更することも、未承認の変更をサブミットすることもできなくなります。

      注意

      strictトリガは、暗黙的にenforceトリガと同じ動作になります。

    • ワークフロー機能が無効になっている場合(ワークフロー機能はデフォルトで有効になっています)、ワークフロートリガタイプをコメント化してください。ワークフロー機能が有効になっている場合、上記のenforceトリガとstrictトリガをコメント化する必要があります。

      • 重要

      既知の制約事項

      ワークフロートリガは、Swarm 2018.1以前のバージョンで使用可能な以下のトリガ機能をサポートしていません。

      • EXEMPT_FILE_COUNT: 正の整数を設定すると、ファイル数がその値以上であるコミットは、enforce検証またはstrict検証から除外されます。
      • EXEMPT_EXTENSIONS: ファイル拡張子のコンマ区切りリスト。これらの拡張子が付いているファイルを使用したコミットは、enforceまたはstrictの検証の対象外となります。

      引き続きこの機能を使用する場合は、ワークフロー機能を無効にした状態で、既存のenforceトリガとstrictトリガをそのまま使用する必要があります。

      ヒント

      デフォルト設定の場合、すべてのグループメンバーとユーザは、チェンジリストとレビューに適用されるワークフロールールに従う必要があります。ただし、Swarm管理者は、以下のワークフロールールから除外されるグループとユーザを設定することができます。この設定は、Swarmの UI、P4Dコマンドライン、P4Dクライアント、Swarm APIで実行される操作に適用されます。

      以下のトリガタイプは、ワークフロールール用としてSwarmで使用されます。これらのトリガは、カスタムのトリガスクリプト用のトリガではありません。

      • checkenforced: このタイプは、Swarmの[レビューありのコミット時]ワークフロールールで使用されます。このタイプの設定を変更することはできません。checkenforcedは、Helixサーバ change-submitイベントでトリガされます。

        • [レビューありのコミット時]ルールが[承認済みでない場合は却下]に設定されているブランチにレビューが関連付けられていない場合(または、関連付けられているレビューが承認されていない場合)、そのブランチに対してコミットを実行しても却下されます。上記のブランチに承認済みのレビューが関連付けられている場合は、checkstrictによって内容の確認処理が実行されます。

      • checkstrict: このタイプは、Swarmの[レビューなしのコミット時]ワークフロールールで使用されます。このタイプの設定を変更することはできません。checkstrictは、Helixサーバ change-contentイベントでトリガされます。

        • このチェック処理は、checkenforcedの後で実行されます。[レビューなしのコミット時]ルールが[却下]に設定されていて、コミット対象の1つ以上のファイルが、関連付けられているレビューの対象ファイルの内容と一致しない場合は、コミットが却下されます。

      • checkshelve: このタイプは、Swarmの[終了状態のレビューの更新時]ワークフロールールで使用されます。このタイプの設定を変更することはできません。checkshelveは、Helixサーバ shelve-submitイベントでトリガされます。

        • レビューに関連付けられているシェルフを、[終了状態のレビューの更新時]ルールが[却下]に設定されているブランチに対してコミットすると、Swarmにより、そのレビューが保護対象の状態になっていないかどうかが確認されます。レビューが保護対象の状態になっている場合、コミットが却下されます。

    重要

    Swarmトリガタイプを、関係のないHelixサーバイベントと組み合わせて使用することはできません。このような組み合わせを使用すると、動作を判別できず、各タイプの処理で必要な情報をトリガで使用できなくなる可能性があります。

  • -v ID

    IDには、現在のトリガタイプの識別子を指定します。

    typeとして、job、user、userdel、group、groupdel、changesaveのいずれかを設定した場合、IDを%formname%に設定して、Swarmで処理する特定のフォーム識別子を指定する必要があります。

    typeとして、shelve、commit、shelvedel、checkenforced、checkstrict、のいずれかを設定した場合checkshelveIDを%change%に設定して、Swarmで処理する特定のチェンジリストを指定する必要があります。

  • -p port (任意指定) ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    Helixサーバのポート(P4PORT)を指定します。これは、任意指定の値です。トリガの処理中にHelixサーバに対してトリガ専用のコマンドを実行する必要があるため、この値は、enforceタイプまたはstrictタイプでのみ使用されます。

  • -r (任意指定) ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    enforceタイプまたはstrictタイプの処理中に、現在のレビュー対象であるコミットだけが検証されます。

  • -g (任意指定) ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    enforceまたはstrictの検証から除外するグループを指定します。グループとそのサブグループのメンバーが、enforceまたはstrictの検証から除外されます。

  • -c config_file (任意指定)

    設定項目を指定するためのconfig_fileを指定します(任意指定)。

設定項目

swarm-trigger.confファイル(トリガエントリで-cオプションが指定されている場合は別のファイル)では、以下の設定項目が使用されます。

  • SWARM_HOST (必須)

    SwarmインスタンスのホストのURLを指定します。URLの先頭には、http://またはhttps://を指定する必要があります。例: https://myswarm.url

  • SWARM_TOKEN (必須)

    Swarmとの対話で使用されるトークン。このトークンを取得するには、super 権限を持つユーザとしてSwarmにログインし、メインナビゲーションバーにあるユーザメニューで[バージョン情報]Swarmを選択します。

    また、追加のトークンを手動で作成することもできます。トークンは、SWARM_ROOT/data/queue/tokensに保存される空のファイルです(ファイル名は「token」で、[Swarmのバージョン情報]ダイアログに表示されます)。このファイルは、Webサーバによる読み取りが可能な状態になっている必要があります。

    追加のトークンを手動で作成して、JIRAビルドタスクなどのプロセスとSwarmを対話させたり、Swarmの通常の操作を中断することなく、Swarmへのアクセスを個別に無効にしたりすることができます。

  • ADMIN_USER (任意指定)ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    enforceまたはstrictの検証を実行する場合、Helixサーバで、admin 権限を持つユーザの名前を指定しなければならないことがあります。このユーザ名を指定しなかった場合は、現在の環境で設定されているHelixサーバユーザ名がトリガスクリプトで使用されます。

  • ADMIN_TICKET_FILE (任意指定)ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    Helixサーバのチケットファイルがデフォルトの$HOME/.p4ticketsではない状態でenforceまたはstrictの検証を実行する場合、.p4ticketsファイルのパスを指定しなければならないことがあります。

    重要

    Helixサーバで、チケットが admin 権限を持つユーザに属しているかどうかを確認してください。次に、そのユーザが、チケットのタイムアウトがunlimitedに設定されているグループ(または、チケットがタイムアウトになるまでの期間が非常に長いグループ)のメンバーであるかどうかを確認してください。このユーザの認証処理がタイムアウトになると、enforceとstrictの検証が停止します。

  • P4_PORT (任意指定)ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    enforceまたはstrictの検証を実行する場合、Helixサーバのポートの値(P4PORT)を指定しなければならないことがあります。特に、標準ポート以外のポートでHelixサーバが稼働している場合や、Helixサーバでデフォルト以外のホスト名が使用されている場合に、この設定が必要になる可能性があります。

  • P4 (任意指定)ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    Helixサーバのコマンドクライアントであるp4のフルパスを指定します。このオプションを指定する必要があるのは、Helixサーバ環境のPATHでp4が見つからない場合と、enforceまたはstrictの検証を実行する場合だけです。

  • EXEMPT_FILE_COUNT (任意指定)ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    この値を正の整数に設定すると、ファイルカウントがこの値以上であるコミットが、enforceまたはstrictの検証から除外されます。

  • EXEMPT_EXTENSIONS (任意指定) ワークフロー機能が有効になっている場合は使用しないでください(ワークフロー機能はデフォルトで有効になっています)

    ファイル拡張子をコンマで区切ったリスト。これらの拡張子を持つファイルのコミットが、enforceまたはstrictの検証から除外されます。

  • VERIFY_SSL (任意指定)

    Swarm WebサーバでHTTPSを使用する場合は、この値により、SSL証明書の検証を実行するかどうかを制御します。

    デフォルトでは、VERIFY_SSLは1に設定されています。この場合、すべてのSSL証明書が検証されます。Swarm Webサーバで自己署名証明書を使用する場合は、VERIFY_SSLを0に設定する必要があります。

  • TIMEOUT (任意指定)

    Swarmサーバとの通信時に、エラーを返すまでの秒数を設定します。

    デフォルト値は30秒です。

  • IGNORE_TIMEOUT (任意指定)

    Swarmサーバとの通信がタイムアウトになった場合に実行する処理を指定します。例えば、Helixサーバに対して多数のファイルをサブミットしているときにタイムアウトが発生した場合に実行する処理などを指定します。

    次のオプションを指定します。

    • 0を指定すると、Swarmサーバとの通信がタイムアウトになった場合に、サブミット処理が失敗します。これが、デフォルトの設定です。
    • 1を指定すると、Swarmサーバとの通信がタイムアウトになった場合も、サブミット処理が続行されます。この場合、サブミット処理の信頼性が高くなります。

  • IGNORE_NOSERVER (任意指定)

    Swarmサーバとの通信が失敗した場合に実行する処理を指定します。例えば、Swarmサーバがダウンした場合に実行する処理などを指定します。

    次のオプションを指定します。

    • 0を指定すると、Swarmサーバとの通信が失敗した場合に、サブミット処理が失敗します。これが、デフォルトの設定です。
    • 1を指定すると、Swarmサーバとの通信が失敗した場合も、サブミット処理が続行されます。この場合、サブミット処理の信頼性が高くなります。