Webhookの修正計画のPR処理のフィールド

このページでは、Webhookの修正計画に含まれるPR処理の結果、言語パッケージの更新内容、PR操作イベント、書き込みを停止する問題を説明します。 修正計画全体の構造は修正計画の全体像を参照してください。

PR作成が有効で修正計画がある場合、処理対象があればpull_request_summaryとpull_requests、未配信の操作イベントがあればoperations、書き込みを停止する問題があればproblemsを出力します。 operationsとproblemsは、pull_requestsがない場合にも出力されます。

表のフィールド名は、表の前の文で示すオブジェクトからの相対パスです。 「値がないとき」の表記は、レポートのフィールドと同じです。

PR処理のフィールド

remediationのPR処理に関するフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
pull_request_summary	object	状態別のPR処理の項目数	処理対象がなければ省略
pull_requests	objectの配列	更新対象ごとのPR処理結果	処理対象がなければ省略
operations	objectの配列	未配信のPR操作イベント	省略
problems	objectの配列	PRの書き込みを停止する問題	省略

pull_request_summaryのキーと件数の読み方、0件の扱いは、件数の集計を参照してください。

状態値の定義は、PRの状態値を参照してください。

更新対象とPRの対応

pull_requests[]の1要素は、同じリポジトリ・ベースブランチ内で、まとめて更新する対象の処理結果です。 対象のまとめ方はkindによって異なります。

1要素には、作成したPRまたは同じ更新に対応するPRの情報が入ります。 PRを作成できなかった場合も要素が出力されるため、要素数は作成したPR数とは一致しません。

PRを識別するときは、repoとnumberを組み合わせます。

pull_requests[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
kind	string	更新対象の種類	Composeのタグ更新なら省略
key	string	更新対象をまとめた処理単位の識別子	—
repo	string	更新先リポジトリのowner/name	—
base_branch	string	PRの取り込み先となるブランチ	—
path	string	更新対象を代表するリポジトリ内のファイルパス	—
services	stringの配列	更新対象のサービス名またはワークロードを表す一覧	[]
workloads	stringの配列	更新対象のワークロードキー	省略
also_running	objectの配列	同じイメージで稼働しているが更新対象に含まれないサービスの情報	省略
current_ref	string	更新前のイメージ名	""
candidate_tag	string	更新先イメージのタグ	省略
candidate_digest	string	更新先イメージのmanifestまたはイメージインデックスのdigest	省略
status	string	PR処理の状態	—
reason	string	PR処理結果の理由コード	省略
detail	string	PR処理結果を補足する説明文	省略
number	integer	対応するPRの番号	0なら省略
url	string	対応するPRのURL	省略
state	string	対応するPRについて記録された状態	省略
user_modified	boolean	作成時の記録と異なる変更がPRに見つかったかどうか	falseなら省略
target_key	string	編集するファイルと位置の組み合わせを識別する値	省略
update_key	string	同じ編集対象に対する更新内容を識別する値	省略
attempt_key	string	更新内容と作成するコミットの入力を識別する値	省略
fix_target_count	integer	切り詰め前の修正対象の件数	0
fix_targets	objectの配列	この更新で解消する修正対象	省略
fix_targets_truncated	boolean	修正対象の一覧を100件に切り詰めたかどうか	falseなら省略
replaced_by	integer	このPRを置き換えた新しいPRの番号	0なら省略
replacing	objectの配列	このPRが置き換える古いPRごとの進行状況	省略
replaced	integerの配列	このPRへの置き換えが完了した古いPRの番号	省略
item_key	string	対応するlanguage_items[]の要素のkey	省略
language	object	言語パッケージ更新の内容	省略

次のフィールドには補足があります。

• key
  • GitHubへの問い合わせ前から決まる識別子で、PR番号とは別の値
  • 通知間で同じ処理対象を照合するときに使い、items[].keyやdockerfile_items[].keyとの一致は前提にしない
• item_key
  • kindがlanguageの場合に、language_items[].keyと照合する
• target_key
  • 更新の種類、リポジトリ、ベースブランチ、ファイル、編集位置を識別し、更新前後の版が変わっても編集対象が同じなら同じ値
  • 通知間のpull_requests[].target_keyと照合して、同じ編集対象の提案を関連付ける
• update_key
  • イメージ更新では更新前の参照と更新先のタグ・digest、言語パッケージ更新では採用した版や依存ファイルの変更内容を区別する
  • Kubernetesマニフェスト・Kustomize・Helmのvaluesの更新では、作用するワークロードの集合も区別する
  • 通知間のpull_requests[].update_keyと照合して、同じ更新の提案を関連付ける
• attempt_key
  • 同じ更新でも、ベースコミットや変更前後のファイル内容が変わると別の値になる
  • 同じ入力から処理を再開する場合は同じ値になるため、実行回数を数える用途には使わない
  • operations[].attempt_keyと照合して、そのPR作成に関係する操作をまとめる
• target_key・update_key・attempt_key
  • 値はSHA-256を表す64文字の16進文字列で、受信した文字列をそのまま比較する
  • 処理の途中で停止した場合は、まだ決まっていないキーを省略する
• also_running
  • Composeの対応付けがないサービスや、Kubernetesの対応付け・作用先の集合に含まれないワークロードなどが入る
• user_modified
  • PRの先頭コミット、取り込み先、作成元リポジトリなどが作成時の記録と異なる場合にtrue
• replaced_by・replacing・replaced
  • PR番号は、この要素のrepo内の番号
  • replacingとreplacedには、Webhook出力時の件数による切り詰めを行わない

更新対象の種類

kindの値は次のとおりです。

値	意味
省略	Composeのタグ更新で、同じファイル内で同じイメージ参照を使うサービスをまとめる
kubernetes	Kubernetesマニフェストのタグ更新で、同じファイル内で同じイメージ参照を使うコンテナをまとめる
kustomize	Kustomizeのimagesの1項目を更新する
helm_values	Helmのvaluesで設定した1つのキーを更新する
dockerfile	Dockerfileの1つのFROMを更新する
language	1つの依存ファイルのディレクトリについて、パッケージをまとめて更新する

次のフィールドには補足があります。

• path
  • ComposeではComposeファイル、kubernetesではマニフェスト、kustomizeではkustomizationファイル、helm_valuesではvaluesファイル
  • dockerfileではDockerfile
  • languageでは更新対象を代表する依存ファイルで、npmはpackage-lock.json、pnpmはpnpm-lock.yaml、uvはuv.lock、pipはrequirements.txt、Goはgo.mod、Mavenはルートのpom.xml、Gradleはgradle.lockfile
  • 言語パッケージのPRでは、path以外の依存ファイルも変更する場合がある
• services
  • Composeでは、編集するComposeファイル内のサービス名
  • kubernetes・kustomize・helm_valuesでは、ワークロードキー
  • dockerfile・languageでは、各ワークロードキーから取り出した名前を重複なく並べた一覧
  • 取り出す名前は、Composeではサービス名、Kubernetesではワークロード名、所属不明のDockerコンテナではコンテナ名、所属不明のKubernetesコンテナではPod名
• current_ref
  • Compose・kubernetes・kustomize・helm_valuesでは、更新対象が使っている稼働イメージの参照
  • dockerfileでは、更新対象のFROMに指定されたベースイメージの参照
  • languageでは""
• candidate_tag・candidate_digest
  • languageでは省略する

修正対象

pull_requests[].fix_targets[]の1要素は、ある位置のあるパッケージについて解消する脆弱性を表します。 フィールドは次のとおりです。

フィールド名	型	意味	値がないとき
location	string	修正対象が属する編集位置または依存ファイル内の位置	—
vuln_id	string	解消する脆弱性のID	—
package	string	修正対象のパッケージ名	—
ecosystem	string	修正対象のパッケージの種類	省略

次のフィールドには補足があります。

• location
  • Composeではservices.<サービス名>.image
  • kubernetesでは<Kind>/<namespace>/<name>/<container>で、Kindとnameは対応付けたファイル内のオブジェクト、namespaceはワークロードの名前空間
  • kustomizeではimages[<name>].newTag
  • helm_valuesでは設定したhelm_values.key
  • dockerfileでは0始まりのステージ番号を使うstages[<番号>]で、ステージ名があれば小文字にした名前を:<名前>として付ける
  • languageでは依存ファイル内で照合したパッケージの位置で、位置が得られなければ更新対象の依存ファイルのパス
• package
  • 言語パッケージでは、依存ファイルとの照合に使う正規化後の名前になる場合がある

Helmのvaluesでは、mapping形式・文字列形式ともに設定したキーを使います。 たとえばhelm_values.keyがimageなら、locationはimageとなり、mapping形式でタグを変更する場合もimage.tagにはなりません。

一覧は最大100件です。 全件数はpull_requests[].fix_target_countで確認し、100件を超える場合はpull_requests[].fix_targets_truncatedがtrueになります。

件数は脆弱性IDだけでまとめず、位置とパッケージの違いも区別します。 ベースイメージ更新では、検出されたレイヤーの集合が違う対象も別に数えます。

レイヤー情報はこの配列に出力しないため、見えているフィールドが同じ要素を受信側で重複として除かないでください。

PRの置き換え

pull_requests[].replacing[]の1要素は、古いPRをこのPRで置き換える処理の進行状況を表します。

フィールド名	型	意味	値がないとき
old_number	integer	置き換える古いPRの番号	—
state	string	古いPRの置き換え処理の状態	—

stateの値は次のとおりです。

値	意味
pending	置き換えを決め、まだ操作を送っていない
commented	古いPRに置き換えを知らせるコメントがある
closed	クローズ操作を送ったが、結果の確認が済んでいない
done	古いPRを置き換え済みとして記録した
abandoned	置き換えの条件を満たさなくなり、処理を打ち切った

replacing[].stateがclosedでも、クローズの完了確認を表すとは限りません。 replaced[]には、置き換え処理がdoneとなり、古いPRの状態もreplacedと確認された番号が入ります。

置き換えの条件は、古いPRの置き換えを参照してください。

PR処理の例

次の例は、ベースイメージ更新のPRを作成した出力から、集計とPR処理結果を抜粋したものです。

{
  "remediation": {
    "pull_request_summary": {
      "pr_created": 1
    },
    "pull_requests": [
      {
        "kind": "dockerfile",
        "key": "dockerfile|ex/app|main|docker/Dockerfile|stages[0]:runtime",
        "repo": "ex/app",
        "base_branch": "main",
        "path": "docker/Dockerfile",
        "services": ["app"],
        "workloads": ["compose/shop/app"],
        "current_ref": "python:3.12.3-slim",
        "candidate_tag": "3.12.5-slim",
        "status": "pr_created",
        "number": 7,
        "url": "https://github.com/ex/app/pull/7",
        "state": "open",
        "fix_target_count": 2,
        "fix_targets": [
          {
            "location": "stages[0]:runtime",
            "vuln_id": "CVE-2031-0001",
            "package": "libc"
          },
          {
            "location": "stages[0]:runtime",
            "vuln_id": "CVE-2031-0002",
            "package": "libc"
          }
        ]
      }
    ]
  }
}

次の例は、言語パッケージ更新のpull_requests[]の1要素から、対象を表すフィールドを抜粋したものです。

{
  "kind": "language",
  "key": "language|ex/app|main|package-lock.json",
  "repo": "ex/app",
  "base_branch": "main",
  "path": "package-lock.json",
  "services": ["api", "web"],
  "workloads": ["compose/shop/api", "compose/shop/web"],
  "current_ref": ""
}

言語パッケージ更新の内容

pull_requests[].languageは、PRで更新するパッケージと依存ファイルの変更内容を表します。 フィールドは次のとおりです。

フィールド名	型	意味	値がないとき
manager	string	依存ファイルを扱うパッケージマネージャー	—
root	string	リポジトリ内の依存ファイルのディレクトリ	—
packages	objectの配列	更新するパッケージ	[]
manifest_edits	objectの配列	依存ファイルの版指定の変更	省略
chain	objectの配列	再解決のためにあわせて更新する直接依存	省略
remaining	objectの配列	PRの更新から除外したパッケージ	省略

managerの値は次のとおりです。

値	意味
npm	npm
pnpm	pnpm
uv	uv
pip	pip
go	Go modules
maven	Maven
gradle	Gradle

rootがリポジトリのルートを指す場合は、.です。 対応する依存ファイルの形式は、対応する入力形式を参照してください。

更新するパッケージ

pull_requests[].language.packages[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
name	string	更新するパッケージ名	—
ecosystem	string	更新するパッケージの種類	—
relation	string	プロジェクトから見た依存関係の区分	省略
from	string	更新対象のパッケージの稼働版	—
to	string	PRで採用した更新先の版	—
major	boolean	fromからtoへの変更がメジャー版の変更に当たるかどうか	falseなら省略
through	stringの配列	このパッケージを更新するためにあわせて更新した直接依存の名前	省略

relationの値は次のとおりです。

値	意味
direct	プロジェクトが直接要求する依存
transitive	別のパッケージを経由する依存
mixed	直接依存と別のパッケージを経由する依存が混在

次のフィールドには補足があります。

• from
  • 作成済みのPRに対応付けた回は、その回の計画で確認した稼働版
• major
  • 0.xではマイナー版の変更もtrue
  • 版を読み取れず比較できない場合も省略するため、省略だけで変更の安全性を判断しない
• through
  • 更新前後の版は、同じ名前のpull_requests[].language.chain[]で確認する

依存ファイルの版指定の変更

pull_requests[].language.manifest_edits[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
file	string	版指定を書き換えるリポジトリ内のファイルパス	—
section	string	版指定がある依存宣言の区分	—
name	string	版指定を書き換えるパッケージ名	—
from	string	変更前の版指定	—
to	string	変更後の版指定	—
major	boolean	変更後の版指定が変更前に許していたメジャー版を許さなくなるかどうか	falseなら省略

sectionには、dependenciesやproject.dependenciesなど、依存ファイル内の区分が入ります。 fromとtoは^4.17.15のような版指定で、実際に採用した版はpull_requests[].language.packages[].toで確認します。

あわせて更新する直接依存

pull_requests[].language.chain[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
name	string	あわせて更新する直接依存の名前	—
from	string	直接依存の変更前の版	""
to	string	直接依存の変更後の版	""
held	string	古い版を指定されていたパッケージ名	省略
held_range	string	更新を妨げていた版指定	省略
held_by	string	直接依存とheldの間で古い版を指定していたパッケージ名	省略

held_byは、直接依存自身が古い版を指定している場合には省略します。 再解決の条件は、再解決の検査条件を参照してください。

PRの更新から除外したパッケージ

pull_requests[].language.remaining[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
name	string	PRの更新から除外したパッケージ名	—
ecosystem	string	除外したパッケージの種類	—
relation	string	プロジェクトから見た依存関係の区分	省略
from	string	除外したパッケージの稼働版	—
target	string	予定していた更新先の下限の版	""
reason	string	更新から除外した理由コード	—
detail	string	除外理由を補足する説明文	省略
maven_bom	object	更新先の下限に届くBOMの情報	省略

作成済みのPRに対応付けた回は、pull_requests[].language.remaining[]から、同じ名前とエコシステムのlanguage_items[].packages[]へ除外情報を補います。 language_items[].update_executedとlanguage_items[].post_update_check_executedがfalseでも、language_items[].packages[]にleft_out: true、action: "manual"、reasonが付く場合があります。

補足があればlanguage_items[].packages[].detail、該当するBOM情報があればlanguage_items[].packages[].maven_bomにも反映します。 global_node_modulesを理由とするパッケージは、この補完の対象外です。

部分的な更新の読み方は、部分PRを参照してください。

除外したパッケージのBOM情報

pull_requests[].language.remaining[].maven_bomのフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
bom	string	BOMのgroupId:artifactId	—
property	string	BOMの版を指定するプロパティ名	省略
from	string	プロジェクトが取り込んでいるBOMの版	—
to	string	対象パッケージを更新先の下限以上で管理するBOMの候補版	—
manages	string	toのBOMが管理する対象パッケージの版	—

このオブジェクトは、pull_requests[].language.remaining[].reasonがmaven_bom_series_unreachedで、BOMの候補情報がある場合に出力します。 BOMの版はfromとto、対象パッケージの版はmanagesで区別してください。

候補の意味は、版の出所と書き換えとGradleの版の宣言と書き換えを参照してください。

言語パッケージ更新の例

次の例は、pull_requests[].languageの出力です。

{
  "manager": "npm",
  "root": ".",
  "packages": [
    {
      "name": "lodash",
      "ecosystem": "node-pkg",
      "relation": "direct",
      "from": "4.17.15",
      "to": "4.17.21"
    },
    {
      "name": "minimist",
      "ecosystem": "node-pkg",
      "relation": "transitive",
      "from": "1.2.5",
      "to": "1.2.6"
    }
  ],
  "manifest_edits": [
    {
      "file": "package.json",
      "section": "dependencies",
      "name": "lodash",
      "from": "4.17.15",
      "to": "4.17.21"
    }
  ]
}

部分PRの例

部分PRは、まとめて更新しようとしたパッケージの一部だけを更新したPRです。

次の例は、部分PRを含むペイロードから主要なフィールドだけを抜粋したものです。 更新できたパッケージと、更新から除外したパッケージの記録先を確認してください。

• 更新できたexample-aは、この例ではlanguage_items[].packages[]だけに記録
• 更新から除外したexample-bは、language_items[].packages[]にleft_out: true付きで、pull_requests[].language.remaining[]にも記録

{
  "remediation": {
    "language_items": [
      {
        "category": "pr_candidate",
        "update_executed": true,
        "post_update_check_executed": true,
        "packages": [
          {
            "name": "example-a",
            "ecosystem": "node-pkg",
            "installed": "1.0.0",
            "adopted_version": "1.0.1",
            "action": "update",
            "reason": "update_verified"
          },
          {
            "name": "example-b",
            "ecosystem": "node-pkg",
            "installed": "2.0.0",
            "selection_lower_bound": "2.0.1",
            "action": "manual",
            "reason": "target_not_updated",
            "left_out": true
          }
        ]
      }
    ],
    "pull_requests": [
      {
        "kind": "language",
        "language": {
          "remaining": [
            {
              "name": "example-b",
              "ecosystem": "node-pkg",
              "from": "2.0.0",
              "target": "2.0.1",
              "reason": "target_not_updated"
            }
          ]
        }
      }
    ]
  }
}

採用条件は、部分PRの成立条件を参照してください。

PR操作イベントのフィールド

operations[]は、まだ配信済みとして記録されていないPR操作イベントを、連番の昇順で出力します。 1つの操作について、送信前の記録、操作結果、後から確認した結果は、それぞれ別のイベントです。

operations[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
seq	integer	同じPR処理の保存記録内で増加するイベントの連番	—
id	string	同じ操作の各段階を関連付ける識別子	—
at	string	イベントを記録したUTCのRFC 3339形式の時刻	—
phase	string	操作のどの段階を記録したイベントかを表す値	—
kind	string	GitHubに対する書き込み操作の種類	—
repo	string	操作対象リポジトリのowner/name	—
attempt_key	string	関係するPR作成の試行内容を識別する値	省略
number	integer	操作対象のPR番号	0なら省略
result	string	操作の結果	省略
error	string	エラーまたは結果の確認内容を補足する説明文	省略

phaseの値は次のとおりです。

値	意味
intent	操作を送る前に、その操作を行う予定を記録した
result	操作を送った後に、得られた結果を記録した
settled	結果が不明だった操作を後の処理で確認し、扱いを確定した

kindの値は次のとおりです。

値	意味
create_blob	Gitのファイル内容を作成する
create_tree	Gitのファイル構成を作成する
create_commit	コミットを作成する
create_ref	PR用のブランチを作成する
create_pull	PRを作成する
create_comment	PRに置き換えを知らせるコメントを作成する
close_pull	置き換え対象のPRをクローズする

resultの値は次のとおりです。

値	意味
ok	操作の成功を確認できた
failed	操作の失敗または目的の変更が成立していないことを確認した
unknown	操作の成否を確定できない

次のフィールドには補足があります。

• seq
  • リポジトリごとではなく、同じ保存記録を共有するPR処理全体で増加する
  • 再送された同じイベントは同じ値を持つ
• id
  • 最初のイベントの連番を使うop-<連番>形式
  • 同じ操作のintent・result・settledで共通するが、各イベントのseqは異なる
• attempt_key
  • pull_requests[].attempt_keyと照合でき、1つの値に複数の操作のidが対応する
  • 過去の未配信イベントも含むため、その通知のpull_requests[]に照合先があるとは限らない
• number
  • コメント作成やクローズでは操作対象の番号で、PRを新規作成するイベントでは成功後も省略される場合がある
• phase
  • intentだけでは、GitHubへ操作を送ったことまでは確認できない
  • settledでも、作成されたか不明なGitのファイル内容・ファイル構成・コミットを使わずにやり直す場合は、resultがunknownのままになる
• error
  • 固定コードではなく説明文で、settledではresultがokでも確認内容が入る場合がある

受信側でイベントの重複を除くときは、同じ送信元の同じ保存記録に属するseqを使います。 idやattempt_keyだけで重複を除くと、同じ操作の結果や後から確認したイベントを取りこぼします。

seqとidは、保存記録の初期化後に再使用されます。 Webhookには送信元を一意に識別する値や保存記録の初期化を識別する値がなく、environment.kind・environment.nameの一意性も保証されません。

複数の送信元や初期化前後のイベントは、受信データだけでは確実に区別できません。 送信元ごとに受信URLを分け、保存記録を初期化した際に受信側の重複判定の記録を切り替えるなど、運用上の対応が必要です。

配信と再送の扱いは、修正計画の再送を参照してください。

書き込み停止のフィールド

problems[]は、PRの書き込みを停止する問題を表します。 問題が続く間は各回の計画に含まれ、同じ計画ではcode・repo・targetの組み合わせごとに1件となります。

problems[]の1要素のフィールドは次のとおりです。

フィールド名	型	意味	値がないとき
code	string	書き込みを停止する問題の分類	—
repo	string	問題があるリポジトリのowner/name	全リポジトリに関わる場合は省略
target	string	問題があるファイルと対象位置を表す表示用文字列	対象を限定しない場合は省略
reason	string	問題の具体的な原因を示す理由コード	省略
detail	string	問題の内容を補足する説明文	省略

codeの値は次のとおりです。

値	意味
write_blocked	記録とGitHub上の状態の不一致や処理の準備失敗などにより、書き込みを停止した
storage_failed	修正計画またはPR処理の記録を保存できず、書き込みを停止した
storage_full	操作イベントの保存領域に空きを確保できず、新しい書き込みを停止した
records_unverified	PRの記録を確認できず、書き込みを停止した

codeは問題の大きな分類、reasonはその原因です。 たとえばcodeがwrite_blockedのとき、reasonでbranch_not_oursやattempt_unsettledなどの原因を区別します。

次のフィールドには補足があります。

• repo
  • 値があれば、pull_requests[].repoと照合する
• target
  • <ファイルパス> (<対象位置>, <対象位置>)の形式で、対象位置が1つなら括弧内も1つ
  • ファイルパスはpull_requests[].path、Compose・Kubernetes・Kustomize・Helmのvalues・Dockerfileの対象位置はpull_requests[].fix_targets[].locationと照らし合わせる
  • 言語パッケージ更新の対象位置は依存ファイルのディレクトリで、pull_requests[].language.rootに対応する
  • pull_requests[].keyやpull_requests[].target_keyと完全一致する照合キーではない
  • fix_targetsの省略・切り詰めや処理対象の変化があるため、その通知だけで対応するpull_requests[]の要素を特定できない場合がある
  • repoがありtargetがなければ、そのリポジトリ全体に関わる問題

停止条件は、書き込みの停止を参照してください。