Appearance
AssemblyLineの連携設定 - Webhook
ここではAssemblyLineに対し、 Webhookを設定します。 これにより、アプリケーションコードの変更をトリガとして、AssemblyLineを実行できます。
設定の流れ
Git Repositoryでコードがpushされた際に、Git push eventをトリガとしてAssemblyLineを起動するように設定します。
- 左メニューより、Repositoryを選択します。
- Repository一覧より、コードの変更をトリガしたいリポジトリを選択します。
- 右上の
WEBHOOKボタンを押下し、Webhook設定画面を開きます。 - 右上の
NEW TRIGGERボタンを押下します。 - 下記に従い、各フォームに入力します。
実行したいAssemblyLineをプルダウンから選択します。
トリガ対象のbranchもしくはtagを設定します。 条件は正規表現で記述し、複数指定できます。どれかに一つにマッチした場合はトリガ対象となります。
トリガ対象のfile pathを任意で設定します。 指定しない場合は全ての変更が対象となり、指定した場合は、変更対象のファイルのうち条件に合致するものが存在する場合に限りトリガ対象となります。 条件は正規表現で記述し、複数指定できます。どれかに一つにマッチした場合はトリガ対象となります。
トリガ対象から除外する条件を任意で指定します。 指定しない場合は全ての変更が対象となり、指定した場合は、Git push eventのペイロードが条件に合致する場合は除外されます。
- Attribute Path: Git push eventのjsonペイロードのうち、どのフィールドを検査するかを指定します。
- Ignore Condition Regex: 対象のフィールドの値を検査する正規表現を記述します。
AssemblyLineを実行する際の引数を設定します。
- Parameter Bindingsの項に、AssemblyLine実行時に必要なパラメータが表示されますので、挿入したい値を入力します。
$(body.foo.0.bar)という形式で記述することで、Git push eventのWebhookペイロードからフィールド値を抜き出して挿入できます。例えばGitHubでは、 Webhookペイロード中のafterキーには 最新のコミット SHA が保持されており、$(body.after)と記述することで その値を挿入できます。
Info
先頭にWebhookペイロードのルートを示す固定値
bodyを指定し、続けて参照したいフィールド値に至るまでのpathを、objectの場合はkey、arrayの場合は要素番号を使用し、.で結合して表現してください。- また挿入する値には、トリガ対象のbranchもしくはtagの条件を記述した正規表現に合致した値を抽出して使用できます。詳細な記述方法についてはWebhookペイロードの値の抽出と使用を参照してください。
- 設定内容が正しいことを確認し、Saveします。
- トリガ作成後、Webhook詳細の画面にて、GitHubなどのevent通知側と共有するsecretを生成できます。secretを設定することで、secretが誤っているpush eventが来たときに不正なrequestとしてトリガ対象から除外できます。
- Webhook設定にて、Secret作成ボタンを押下します。
- Secretが生成され画面に表示されるので、値をメモします。
- GitHubなどGit eventをpushするシステムにて、上記secretを設定します。
- Secret作成後、
RESETボタンを実行することで、Secretをrevokeして再生成できます。
Webhook詳細画面の項目について
Branch / Tag Conditions (Required)
AssemblyLineを実行する対象のブランチまたはタグ名を正規表現で指定します。
ブランチまたはタグ名のフォーマットはリポジトリプロバイダに応じて異なります。詳細はよく使う正規表現を参照してください。
また、正規表現のグループ表記 (e.g. foo/bar/(.*) ) を使用することで、部分一致を Parameter Bindings で使用することも出来ます。 例えばタグに refs/tags/v1.2.3 が指定された場合に、バージョンの v1.2.3 を抜き出したいといった場合に使用します。
詳細な記述方法についてはWebhookペイロードの値の抽出と使用を参照してください。
設定例
GitHub/GitLab/Backlogのmainブランチを対象とする場合は以下を設定します。
^refs/heads/main$
Bitbucketのmainブランチを対象とする場合は以下を設定します。
^main$
GitHub/GitLab/Backlogのタグ名よりバージョンを取得します。
^refs/tags/(v[0-9]+\.[0-9]+\.[0-9])$
File Paths (Optional)
Webhookで通知された更新ファイルのうち、絞り込みたいファイルパスを正規表現で指定します。 複数指定されている場合、ペイロードに含まれる更新ファイルのパスがいずれかの条件にマッチしているかどうかをチェックします。条件にマッチしない場合はAssemblylineは実行されません。
設定例
srcディレクトリ内のファイル、または config ディレクトリ直下（サブディレクトリは含まない）の yaml を対象とする場合は以下を設定します。
^src/.*$^config/[^/]*\.yaml$
srcディレクトリ以下を対象とするが、.gitignoreファイルは対象外とする場合は以下のように指定します。
^src\/(?!.*\.gitignore).*
Ignoring Conditions (Optional)
Webhookペイロードの値を抽出し、条件にマッチした場合にAssemblyLineの実行を抑止します。 Branch / Tag Conditions や File Pathes などの項目でも絞り込みが出来ますが、任意のパスの条件を指定したい場合に使用します。
抽出はキーを指定する Attribute Path と、条件を正規表現で指定する Ignore Condition Regexp のペアをリストで指定します。ペイロードがいずれかの条件にマッチしている場合はAssemblyLineが実行されません。
Attribute Path$(foo.0.bar)という形式で記述します
Ignore Condition Regexp- 指定したパスの値を正規表現で指定します。
Info
参照したいフィールド値に至るまでのpathを、objectの場合はkey、arrayの場合は要素番号を使用し、. で結合して表現してください。
設定例
GitHubにpushしたユーザ名が GithubAction で始まるものを除外する場合は以下の通りとなります。
Attribute Pathpusher.name
Ignore Condition Regexp^GithubAction.*
Info
Branch / Tag Condition、 File Pahts およびIgnoring Conditions のそれぞれの条件を組み合わせた場合はAND条件として評価されます。
Parameter Bindings (Optional)
Webhookペイロードの値を抽出し、Webhookにより実行されるAssemblyLineの入力パラメータに設定します。 AssemblyLineの入力パラメータとしてGitリビジョンやタグを渡したい場合などに使用します。
設定はAssemblyLineの入力パラメータを指定する Parameter Name と、Webhookペイロードの値を指定する Value のペアをリストで指定します。
Parameter Name- AssemblyLineの入力パラメータを指定します。
Value- 取得したい値のペイロードのパスを
$(body.foo.0.bar)という形式[^1]で記述します。 Branch / Tag Conditionsで指定したブランチまたはタグの部分一致を設定することも出来ます。詳細な記述方法についてはWebhookペイロードの値の抽出と使用を参照してください。
- 取得したい値のペイロードのパスを
設定例
GitHubのコミットSHAを、AssemblyLineの入力パラメータ gitRevision に設定する場合は以下の通りとなります。
Parameter NamegitRevisionを選択する。
Value$(body.after)を入力する。
各リポジトリプロバイダでのWebhook設定
Webhookの設定手順については、各プロバイダの公式ドキュメントを参照してください。
Backlog
Gitリポジトリ作成時、もしくはGitリポジトリの編集時に設定します。 Gitリポジトリ作成 - Backlog enterprise JapaneseGitリポジトリの編集 - Backlog enterprise Japanese
Info
- インテグレーションのWebhook設定はサポートしていません。 Webhook – Backlog ヘルプセンター
- 公式ドキュメントに書かれたペイロードと実際に送られてくるペイロードが異なることをご留意ください。 Git Webフック - Backlog enterprise Japanese
Bitbucket
リポジトリ画面左部のペインからRepository settingsからWebhooksを選択します。 Webhook の作成とトリガのチュートリアル | Bitbucket Cloud | アトラシアン サポート
GitHub
リポジトリ画面上部のSettingsからWebhooksを選択します。 webhookの作成 - GitHub Docs
Warning
Content-Typeはapplication/jsonを選択してください。Secretは必須となります。
GitLab
プロジェクト画面左部のSettingsからWebhooksを選択します。 Webhooks | GitLab
Warning
Secret tokenは必須となります。
Webhookペイロードの値の抽出と使用
Parameter Bindingsの項では、Webhookペイロードの値を抽出し、Webhookにより実行されるAssemblyLineの入力パラメータに挿入できます。値の抽出は、正規表現で抽出できます。 また、トリガ対象のbranchもしくはtagの条件を記述した正規表現に合致した値は、組み込み変数$(conditions.<index>.match)として使用できます。具体的には、記述した文字列中の()に含まれる正規表現に合致した値を抽出して、利用できます。 変数$(conditions.<index>.match)は合致する表現が存在しなかった場合は空文字となりますので、Parameter Bindingsの値として空文字が設定されることをご留意ください。
例: 条件の一つ目に^refs/tags/(v[0-9]+\.[0-9]+\.[0-9])$と設定した場合、v[0-9]+\.[0-9]+\.[0-9]に合致した文字列を抽出できます。 そしてParameter Bindingsの項では、その抽出した値を$(conditions.1.match)という変数で使用できます。二つ目の条件として何らかの正規表現を記述した場合、そこから抽出した値は$(conditions.2.match)として使用できます。
よく使う正規表現一覧
Branch / Tag Conditions
Webhookのトリガ条件として使われます。
mainブランチ
| プロバイダ | 正規表現 |
|---|---|
| Bitbucket | ^main$ |
| Backlog | ^refs/heads/main$ |
| GitHub | ^refs/heads/main$ |
| GitLab | ^refs/heads/main$ |
セマンティックバージョニングによるタグ
| プロバイダ | 正規表現 |
|---|---|
| Bitbucket | ^(v[0-9]+\.[0-9]+\.[0-9])$ |
| Backlog | ^refs/tags/(v[0-9]+\.[0-9]+\.[0-9])$ |
| GitHub | ^refs/tags/(v[0-9]+\.[0-9]+\.[0-9])$ |
| GitLab | ^refs/tags/(v[0-9]+\.[0-9]+\.[0-9])$ |
Parameter Bindings
Webhookにより実行されるAssemblyLineの入力パラメータに対し、Webhookペイロードからフィールド値を挿入できます。 コミットID
| プロバイダ | 正規表現 |
|---|---|
| Bitbucket | $(body.push.changes.0.new.target.hash) |
| Backlog | $(body.content.revisions.0.rev) |
| GitHub | $(body.after) |
| GitLab | $(body.after) |
Webhookペイロードの必須プロパティについて
Webhookペイロードのうち、必須プロパティが指定されていない場合は、Webhookの受付でHTTPステータスコード400を応答します。CI/CDツールやカスタムスクリプトなどを使用してペイロードを指定する場合は、必須プロパティが指定されていることをご確認ください。尚、Project設定画面でSlack通知の設定をしている場合は、Webhookの起動に失敗した場合にエラー通知が投稿されます。
各レポジトリプロバイダで使用するプロパティは以下の通りです。
Info
表存在しないプロパティは無視されます
Backlog
| プロパティ | データ型 | Required | 説明 |
|---|---|---|---|
| ref | 文字列 | Yes | イベントのリファレンスです。 |
| before | 文字列 | Yes | イベント前の状態です。 |
| after | 文字列 | Yes | イベント後の現在の状態です。 |
| revisions | 配列 | Yes | イベントに関連するリビジョンの配列です。 |
| revisions.added | 配列 | Yes | リビジョンで追加されたファイルの配列です。 |
| revisions.removed | 配列 | Yes | リビジョンで削除されたファイルの配列です。 |
| revisions.modified | 配列 | Yes | リビジョンで変更されたファイルの配列です。 |
Bitbucket
| プロパティ | データ型 | Required | 説明 |
|---|---|---|---|
| push | オブジェクト | Yes | プッシュに関する詳細です。 |
| push.changes | 配列 | Yes | 変更内容の配列です。 |
| push.changes.old | オブジェクト | No | 変更前の状態に関する詳細です。 |
| push.changes.old.name | 文字列 | Yes | 変更前の名前です。 |
| push.changes.old.type | 文字列 | Yes | 変更前のタイプです。 |
| push.changes.old.target | オブジェクト | Yes | 変更前のターゲットに関する詳細です。 |
| push.changes.old.target.type | 文字列 | Yes | 変更前のターゲットのタイプです。 |
| push.changes.old.target.hash | 文字列 | Yes | 変更前のターゲットのハッシュです。 |
| push.changes.new | オブジェクト | No | 変更後の状態に関する詳細です。 |
| push.changes.new.name | 文字列 | Yes | 変更後の名前です。 |
| push.changes.new.type | 文字列 | Yes | 変更後のタイプです。 |
| push.changes.new.target | オブジェクト | Yes | 変更後のターゲットに関する詳細です。 |
| push.changes.new.target.type | 文字列 | Yes | 変更後のターゲットのタイプです。 |
| push.changes.new.target.hash | 文字列 | Yes | 変更後のターゲットのハッシュです。 |
| actor | オブジェクト | Yes | イベントのアクターに関する詳細です。 |
| actor.display_name | 文字列 | No | アクターの表示名です。 |
| actor.nickname | 文字列 | No | アクターのニックネームです。 |
GitHub
| プロパティ | データ型 | Required | 説明 |
|---|---|---|---|
| ref | 文字列 | Yes | イベントのリファレンスです。 |
| before | 文字列 | Yes | イベント前の状態です。 |
| after | 文字列 | Yes | イベント後の現在の状態です。 |
| pusher | オブジェクト | No | イベントのpush実施ユーザに関する詳細です。 |
| pusher.name | 文字列 | Yes | push実施ユーザの名前です。 |
| pusher.email | 文字列 | No | push実施ユーザのメールアドレスです。 |
| commits | 配列 | Yes | イベントに関連するコミットの配列です。 |
| commits.added | 配列 | Yes | コミットで追加されたファイルです。 |
| commits.removed | 配列 | Yes | コミットで削除されたファイルです。 |
| commits.modified | 配列 | Yes | コミットで変更されたファイルです。 |
GitLab
| プロパティ | データ型 | Required | 説明 |
|---|---|---|---|
| ref | 文字列 | Yes | イベントのリファレンスです。 |
| before | 文字列 | Yes | イベント前の状態です。 |
| after | 文字列 | Yes | イベント後の現在の状態です。 |
| commits | 配列 | Yes | イベントに関連するコミットの配列です。 |
| commits.added | 配列 | Yes | コミットで追加されたファイルの配列です。 |
| commits.removed | 配列 | Yes | コミットで削除されたファイルの配列です。 |
| commits.modified | 配列 | Yes | コミットで変更されたファイルの配列です。 |