Skip to content

ai pull request scan_ja

Kazushi Kamegawa edited this page Sep 11, 2026 · 2 revisions

AI Scan for pull requests(security.aiPullRequestScan)

English

概要

GitHubは2026-09-10に、AI Scan for pull requestsのREST APIをパブリックプレビューとして公開しました (changelog)。 AI Scanは、PHP、シェル、Terraform、DockerfileなどCodeQLが対応していない言語やフレームワークを対象に、 Pull RequestをAIで検査するGitHubのセキュリティ検出です。 Issue #35でsecurity.aiPullRequestScanを追加し、 plan、apply、import、import --intoでこの設定を扱えるようにします。

状況

PR #36で実装済み、レビュー待ち。 設計は docs/design.mdとdocs/adr.mdのrecord 8・9に記載しています。

以下の計画を書いた後に、変更を2つ追加しました。いずれもAdvanced Securityのない空のprivate リポジトリで検証した際に見つかったものです。

  • ADR record 9。 CodeQL default setupまたはAI Scanの読み取りが403の場合は機能が利用できないものと 扱い、blocked、optional: trueならmanualとし、applyは書き込みを行いません。これがないと、 そのようなリポジトリではoptionalの宣言がupdateを報告し続け、plan --ciが0で終了しません。 importもCodeQL default setupの403で失敗せず、診断として報告します。
  • PRレビュー。 同じapplyの中でoptionalのCodeQL default setupの書き込みが失敗した場合、 AI Scanの依存は満たされないものとして扱います。

このリポジトリでの検証結果: planは両機能をmanualと報告し、apply --yesとplan --ciは0で 終了し、importは診断付きで成功し、import --intoは変更を提案しませんでした。既存の空リポジトリ へのseedは、別の既存の理由により409で失敗するため、 Issue #37で追跡します。

追跡

種別 Issue
親 Issue #35

API

これらのエンドポイントは、クライアントが既に固定しているAPIバージョン2026-03-10で提供されます (RESTリファレンス)。

用途 メソッドとパス Bodyと応答
読み取り GET /repos/{owner}/{repo}/code-scanning/ai-scan {"pr_scan": "enabled" | "disabled"}。Advanced Security無効時は403、ほかに404
書き込み PATCH /repos/{owner}/{repo}/code-scanning/ai-scan Body {"pr_scan": ...}。アーカイブ済みまたはAdvanced Security無効時は403、ほかに422
組織(管理しない) GET/PATCH /orgs/{org}/code-scanning/ai-scan 組織で無効な場合、リポジトリではAI Scanを有効にできない

AI Scanには、GitHub Advanced Security、Copilotライセンス、CodeQL default setup、Enterpriseと組織による 有効化も必要です。利用するとAI creditsを消費します。

設計

  1. 形。 security.aiPullRequestScan: { enabled, optional }とし、FeatureSettingを再利用します。 schemaVersionは1のままです。この変更より古いバイナリは、このキーを未知のフィールドとして拒否します。
  2. リポジトリ単位のみ。 組織のエンドポイントは管理しません。組織ポリシーを手動作業として報告する既存方針と 揃えるためです。組織の設定を理由にGitHubが拒否した書き込みは、他の書き込みと同様に失敗します。
  3. CodeQLへの依存。 enabled: trueの場合だけ、実行後にCodeQL default setupが実質的に有効であることを 要求します。宣言されたcodeqlDefaultSetupを優先し、無ければGitHub上の現在の状態を使います。依存を満たさない 場合はblocked、optional: trueならmanualです。評価方法はdependabotSecurityUpdatesと dependabotAlertsの関係と同じで、apply時にも再確認します。
  4. 順序。 StageSecurityの中でcodeqlDefaultSetupの直後に適用します。新しいstageは作りません。
  5. 読み取れない状態。 planでは読み取り失敗を「不明」として更新を報告します。importでは403と404を 診断として報告し、enabled: falseとは書かずにキーを省略します(ADR記録1)。それ以外のエラーでは importを失敗させます。
  6. プレビュー。 オプトインのフラグや別のヘッダーは設けません。ドキュメントには、APIがパブリック プレビューであることを明記し、前提条件を書き込み前に確認できないためoptional: trueを推奨します。

実装

  • スキーマとconfig: schema/repospec.schema.json、internal/config/config.go
  • APIクライアント: internal/githubapiのAIScanSetting、GetAIScan、UpdateAIScan
  • planner: internal/planner/planner.goのappendSecurityChanges、applyRemainingSecurity、CodeQLの 実効状態を求めるヘルパー
  • importとrefresh: internal/importer/security.go、internal/refresh/plan.go、internal/refresh/jsonapply.go
  • ドキュメント: docs/design.md、docs/adr.mdの記録8、docs/examples/bootstrap.yaml、README.mdと それぞれの_ja

検証

単体テストでは次を確認します。

  • APIクライアント: パス、メソッド、Body、APIバージョンヘッダー
  • planner: noopへの収束、状態不明時の更新、依存の結果(blockedとmanual)、enabled: falseが依存でblockされないこと、apply順(codeql → AI Scan → rulesets)
  • importer: enabled、disabled、403と404の診断、その他のエラー
  • refresh: YAMLとJSONの両方

scripts/verify.shとscripts/verify.ps1で全テスト、vet、ビルドを実行します。その後テスト用リポジトリで、 plan → applyの後にplan --ciが0で終了すること、import --intoが差分を提案しないことを確認します。

スコープ境界

組織単位のAI Scan設定と、リポジトリのAdvanced SecurityやCopilotのライセンスの変更は対象外です。

Clone this wiki locally