GitHubの「GitHub documentation update: added back codeql」は、GitHub全体の仕様変更というより、対象リポジトリでCodeQLによる自動コードスキャンを再び有効化するワークフロー更新として見るのが正確です。主な変更点は、mainブランチへのpush、main向けのpull request、週次スケジュール、手動実行でCodeQL分析が走るようになったことです。管理者や開発者は、単に「セキュリティスキャンが増えた」と捉えるのではなく、Actions実行回数、ブランチ保護、権限設定、ビルド対象、検出アラートの運用まで確認する必要があります。(GitHub)
GitHub documentation update: added back codeqlで変わること
今回の更新では、microsoft/experiment-catalogリポジトリのCodeQLワークフローが変更され、これまで手動実行中心だったCodeQL分析が、開発フローに合わせて自動実行される形になっています。Pull Requestの説明では、CodeQL workflow configurationを更新し、mainブランチで自動セキュリティスキャンを有効化するとされています。(GitHub)
変更後の主なトリガーは次の通りです。
| 実行タイミング | 何が起きるか | 実務上の意味 |
|---|---|---|
mainへのpush | mainブランチに反映されたコードをCodeQLが分析 | マージ後のセキュリティ状態を継続確認できる |
main向けpull request | PR作成・更新時にCodeQLが分析 | マージ前に脆弱性や問題を検出しやすくなる |
| 週次スケジュール | 毎週月曜5:30 UTCにスキャン | コード変更がなくても新しいクエリや検出ロジックで再評価できる |
workflow_dispatch | Actions画面から手動実行 | 設定変更後や緊急確認時に任意実行できる |
GitHub公式ドキュメントでも、CodeQLのワークフローはpush、pull request、scheduleなどのイベントでスキャン頻度を設定でき、pushやpull request時のスキャンは新しい脆弱性やエラーの混入を防ぐのに役立つと説明されています。(GitHub Docs)
これはGitHub全体の強制変更ではない
まず押さえるべき点は、この「added back codeql」は、すべてのGitHub利用者に一律で適用されるプラットフォーム変更ではないことです。対象は特定リポジトリの.github/workflows/codeql.ymlとREADMEの更新であり、各企業・チームの既存リポジトリに自動で反映されるものではありません。Files changedでは、CodeQLワークフローのトリガー追加、C#ビルド行の一部削除、READMEへのCodeQLバッジ追加が確認できます。(GitHub)
ただし、実務上は参考になります。特に、過去にCodeQLを一時停止していたリポジトリ、手動実行だけにしていたリポジトリ、mainブランチの保護を強化したいチームにとっては、再有効化時の設計例として見ておく価値があります。
CodeQLとは何か
CodeQLは、GitHubが提供するコード分析エンジンで、ソースコード内の脆弱性やエラーを検出し、結果をcode scanningアラートとして表示します。GitHub公式ドキュメントでは、CodeQLはコードを分析して結果をGitHubのcode scanningアラートとして表示できる仕組みと説明されています。(GitHub Docs)
対応言語には、C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Rust、Swift、GitHub Actionsワークフローなどがあります。今回の対象ワークフローでは、分析対象としてcsharp、javascript、pythonが設定されています。(GitHub Docs)
通常の静的解析ツールとの違い
CodeQLは単なる文字列検索ではなく、コードをデータベース化してクエリで分析する仕組みです。そのため、入力値の流れ、危険なAPI呼び出し、認証・検証漏れのような問題を検出しやすいのが特徴です。
たとえば、Webアプリケーションでユーザー入力がそのままSQL、ファイルパス、URLリダイレクト、テンプレート出力などに渡されている場合、CodeQLのクエリが問題候補として検出することがあります。ただし、検出結果には誤検知もあり得るため、アラートを機械的にすべて修正するのではなく、影響範囲と再現性を確認する運用が必要です。
変更されたワークフローの中身
現在のcodeql.ymlでは、push、pull_request、workflow_dispatch、scheduleが設定されています。スケジュールは30 5 * * 1で、UTCの毎週月曜5:30に実行される指定です。さらに、actions/checkout、github/codeql-action/init、actions/setup-dotnet、github/codeql-action/analyzeなどが使われています。(GitHub)
重要なのは、CodeQLの実行タイミングだけではありません。C#向けには明示的な.NETセットアップとビルド手順が入り、JavaScriptやPythonなどC#以外の言語ではautobuildが使われる構成になっています。
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
schedule:
- cron: "30 5 * * 1"このような設定により、開発者がPRを出した段階、mainに反映した段階、定期スキャンの段階で、異なる目的のCodeQL分析が実行されます。
影響を受ける対象者
今回の更新から特に学ぶべき対象者は、GitHub管理者、リポジトリ管理者、開発者、セキュリティ担当者です。それぞれ確認すべき観点が異なります。
| 対象者 | 確認すべきこと | 理由 |
|---|---|---|
| GitHub管理者 | GitHub Actions、Code Security、ブランチ保護、課金・実行時間 | CodeQLの自動実行により運用範囲が広がる |
| リポジトリ管理者 | .github/workflows/codeql.yml、対象ブランチ、permissions | スキャン失敗や過剰実行を防ぐため |
| 開発者 | PR上のCodeQLチェック、アラート対応ルール | マージ前に修正が必要になる可能性がある |
| セキュリティ担当者 | code scanning alertsのトリアージ、重大度、例外管理 | 検出結果を放置しない仕組みが必要 |
| DevOps担当者 | CI時間、self-hosted runner、依存関係、ビルド成功率 | スキャン増加がCI/CD全体に影響する可能性がある |
特に、pull request時のCodeQLチェックを必須ステータスチェックにする場合は、開発体験への影響が大きくなります。最初から厳格にブロックするのではなく、数週間はアラート傾向や失敗パターンを観察してからルール化する方が現実的です。
管理者が確認すべき設定
Code scanningが利用可能か確認する
Code scanningはGitHub.com上のパブリックリポジトリで利用できます。また、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server上の組織所有リポジトリでは、GitHub Code Securityが有効であることが条件になります。(GitHub Docs)
社内のプライベートリポジトリで同じ構成を展開する場合は、先に次の点を確認してください。
| 確認項目 | 見る場所 | 判断基準 |
|---|---|---|
| GitHub Actionsが有効か | Repository Settings / Actions | CodeQL workflowが実行できる状態か |
| Code Securityが有効か | Settings / Advanced SecurityまたはCode security | private repoでcode scanningを使えるか |
| 対象言語がCodeQL対応か | リポジトリ内の主要言語 | PHPなど未対応言語中心なら別ツールも検討 |
| Actions minutesに余裕があるか | Organization billing / Actions usage | push・PR・週次実行で消費が増えないか |
| ブランチ保護との関係 | Branch protection rules / Rulesets | CodeQL失敗時にマージを止めるか |
permissionsを最小権限で確認する
今回のワークフローでは、全体としてcontents: read、jobレベルでactions: read、contents: read、security-events: writeが設定されています。security-events: writeはCodeQLの分析結果をcode scanningへアップロードするために重要です。CodeQL ActionのREADMEでも、advanced setupのcode scanning workflowにはsecurity-events: writeが必要で、private repositoryでは追加でcontents: readが必要と説明されています。(GitHub)
権限設定で失敗しやすいのは、組織全体でGITHUB_TOKENを読み取り専用に制限しているケースです。GitHub公式ドキュメントでは、permissionsキーを使ってワークフロー全体またはjob単位でGITHUB_TOKENの権限を調整し、必要最小限のアクセス権を付与することが推奨されています。(GitHub Docs)
開発者が確認すべきポイント
PR作成時にCodeQLチェックが増える
今回の更新では、pull_requestトリガーが有効になっています。これにより、main向けのPRでCodeQL分析が実行されます。GitHub公式ドキュメントでは、pull requestをスキャンした場合、結果はPRのチェック内にアラートとして表示されると説明されています。(GitHub Docs)
開発者は、PRで新たに次のような状況に遭遇する可能性があります。
| 状況 | 起きること | 対応 |
|---|---|---|
| CodeQLチェックが失敗 | PRのChecksが赤になる | Actionsログでビルド失敗か分析失敗かを切り分ける |
| 新規アラートが出る | PR上にセキュリティ指摘が表示される | 該当コード、入力経路、修正案を確認する |
| 既存アラートが表示される | 過去の問題が可視化される | 新規混入か既存債務かを分けて扱う |
| 実行時間が長い | PRのフィードバックが遅れる | 対象パスやビルド手順の最適化を検討する |
重要なのは、CodeQLアラートを「CIの邪魔」と見なさないことです。PR段階で検出されるということは、レビュー担当者がセキュリティ観点を目視だけに頼らなくてよくなるということです。
ローカル確認とCI確認を分けて考える
CodeQLはCI上で実行されるため、開発者がローカルで毎回CodeQLを実行する必要はありません。ただし、C#のようなビルドが必要な言語では、ローカルで対象プロジェクトがビルドできない状態だと、CodeQLも失敗しやすくなります。
今回のワークフローでは、C#分析時に.NET 10.0.xをセットアップし、catalog/exp-catalog.csprojをビルドする構成です。変更前後の差分では、evaluator/evaluator.csprojのビルド行が削除されています。(GitHub)
このような変更は、CodeQL分析の対象やビルド成功率に影響する可能性があります。リポジトリ内に複数プロジェクトがある場合は、「どのプロジェクトをビルドしてCodeQLに見せるのか」を明確にしておくべきです。
移行・展開時の注意点
既存のCodeQL設定と重複させない
GitHubには、CodeQLの設定方法として大きく「default setup」と「advanced setup」があります。default setupはGitHub側が言語、クエリスイート、トリガーを自動選択する方式で、advanced setupはワークフローファイルを追加して細かくカスタマイズする方式です。(GitHub Docs)
今回のように.github/workflows/codeql.ymlを編集する構成は、実質的にadvanced setup寄りの運用です。既にdefault setupを使っているリポジトリへ同様のワークフローを追加すると、設定が重複したり、意図しない分析が増えたりする可能性があります。
展開前には、次の順番で確認してください。
| 手順 | 作業 | チェックポイント |
|---|---|---|
| 1 | 現在のCodeQL設定を確認 | default setupかadvanced setupか |
| 2 | 既存ワークフローを確認 | .github/workflows内にCodeQL関連が複数ないか |
| 3 | 対象ブランチを決める | mainだけか、release・developも含めるか |
| 4 | 対象言語を決める | 実際の主要言語とmatrixが一致しているか |
| 5 | 初回実行を確認 | Actionsログ、Securityタブ、PRチェックを見る |
| 6 | ブランチ保護に組み込むか判断 | 安定してから必須チェック化する |
スケジュール実行の時刻に注意する
今回のスケジュールはUTCで月曜5:30です。日本時間では通常、月曜14:30です。業務時間中にCIリソースを消費する可能性があるため、組織内でActionsの混雑やself-hosted runnerの利用状況を見て調整するとよいでしょう。
GitHub公式ドキュメントでは、default CodeQL analysis workflowはイベントによるスキャンに加えて週1回スキャンし、スケジュールはon.scheduleのcron値で調整できると説明されています。(GitHub Docs)
実務では、次のような判断が有効です。
| チームの状況 | おすすめ設定 |
|---|---|
| 小規模チームでActions負荷が低い | 週1回のままでよい |
| 月曜午前にCIが集中する | 日本時間の夜間や休日にずらす |
| releaseブランチを長期運用している | main以外の重要ブランチも検討 |
| 大規模モノレポ | paths、言語matrix、runner性能を見直す |
Dependabot PRでは権限エラーに注意する
CodeQLをPRで動かす場合、DependabotのPRや自動更新ブランチで権限エラーが出ることがあります。GitHub公式ドキュメントでは、Dependabotがトリガーしたワークフローでは読み取り専用スコープで実行される場合があり、code scanning結果のアップロードには通常security-events: writeが必要と説明されています。一方で、pull_requestイベントで実行された場合は結果アップロードが許可されるため、Dependabotブランチではpushよりpull_requestイベントの利用が推奨されています。(GitHub Docs)
そのため、Dependabotを使っているチームは、次の点を確認してください。
- DependabotのPRでCodeQLチェックが失敗していないか
pushだけでなくpull_requestトリガーが設定されているかsecurity-events: writeがjobに付与されているか- ブランチ保護で失敗時に全PRが止まらないか
READMEへのCodeQLバッジ追加の意味
今回の更新では、READMEにCodeQLバッジも追加されています。Files changedでは、OpenSSF Scorecardバッジに加えて、CodeQL workflowのバッジがREADMEに追加されたことが確認できます。(GitHub)
バッジは単なる見た目の装飾ではありません。外部コントリビューターや利用者に対して、リポジトリがセキュリティスキャンを継続的に実行していることを示すシグナルになります。
ただし、バッジには注意点もあります。CodeQLバッジが緑だからといって、リポジトリに脆弱性がないことを保証するものではありません。あくまで「ワークフローが成功している」ことを示すものであり、検出対象外の言語、未分析のパス、誤検知・見逃しの可能性は残ります。
自社リポジトリへ適用する場合の設定例
同じようにmainブランチでCodeQLを再有効化するなら、まずは最小構成から始めるのが安全です。
name: "CodeQL"
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
schedule:
- cron: "30 5 * * 1"
permissions:
contents: read
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: false
matrix:
language: [javascript-typescript, python]
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
with:
category: "/language:${{ matrix.language }}"実際に使う際は、リポジトリの主要言語に合わせてmatrix.languageを調整してください。C#、Java、Goなどビルドが必要な言語では、initとanalyzeの間にビルド手順を入れるか、CodeQLのビルドモードを見直す必要があります。
CodeQL ActionのREADMEでは、compiled languagesではmanual、autobuild、noneといったビルドモードがあり、manualは一般に精度が高い一方で設定が難しく、autobuildは簡単だがプロジェクトによっては失敗する可能性があると説明されています。(GitHub)
失敗しやすいポイントと対策
CodeQLの再有効化でよくある失敗は、設定自体ではなく、運用設計の不足から起きます。
| 失敗しやすいポイント | 原因 | 対策 |
|---|---|---|
| PRがなかなかマージできない | CodeQLが失敗し、必須チェックで止まる | 安定稼働を確認してから必須化する |
| Actions使用量が急増する | push、PR、scheduleで実行回数が増える | 対象ブランチとスケジュールを絞る |
| C#やJavaの分析が失敗する | 必要なSDK、依存関係、ビルド手順が不足 | CIと同等のビルド手順をCodeQLにも入れる |
| アラートが放置される | 担当者や優先度ルールがない | High/Criticalから対応する運用を決める |
| バッジだけ追加して満足する | 結果確認のプロセスがない | SecurityタブとPRチェックを定期確認する |
| default setupとadvanced setupが混在する | 移行方針が曖昧 | どちらかに統一し、重複スキャンを避ける |
特に重要なのは、最初の数回の実行結果です。初回は既存コード由来のアラートがまとまって出ることがあります。すべてを一気に直そうとすると開発が止まりやすいため、重大度、外部入力に近い箇所、本番利用されているコードから優先順位を付けると現実的です。
ブランチ保護に組み込むべきか
CodeQLを有効化した後、次に悩むのが「CodeQLチェックを必須にするか」です。
結論として、すぐに必須化するより、まずは観察期間を置くことをおすすめします。特に既存リポジトリでは、古いアラート、ビルド不安定、依存関係の取得失敗などが原因で、PRマージが止まる可能性があります。
段階的には、次の流れが安全です。
| フェーズ | 運用 | 目的 |
|---|---|---|
| 導入直後 | CodeQLを任意チェックとして実行 | 失敗率、実行時間、アラート量を把握 |
| 安定後 | 新規アラートをレビュー対象にする | セキュリティレビューの習慣化 |
| 運用定着後 | High/Critical相当の対応ルールを決める | 重大リスクの放置を防ぐ |
| 最終段階 | ブランチ保護やrulesetに組み込む | マージ前の品質ゲートにする |
ブランチ保護に組み込む場合は、CodeQLのチェック名が言語ごとに分かれる点にも注意してください。matrixで複数言語を分析している場合、Analyze (csharp)、Analyze (javascript)のように複数チェックが表示されることがあります。必須チェックの指定を誤ると、一部の言語だけが保護対象になったり、存在しないチェック名を待ち続けたりする原因になります。
今回の更新から学べる実務上のポイント
今回の「GitHub documentation update: added back codeql」は、単にCodeQLを戻しただけの変更ではありません。実務上は、次の3点が重要です。
第一に、セキュリティスキャンを手動実行から開発フローへ組み込んでいる点です。PR、mainへのpush、週次スキャンを組み合わせることで、マージ前・マージ後・定期再評価の3段階で確認できます。
第二に、READMEへCodeQLバッジを追加し、スキャン状態を外部から見える形にしている点です。これはオープンソースや社内共通ライブラリでは、利用者への信頼材料になります。
第三に、ビルド対象を調整している点です。CodeQLは「有効化すれば終わり」ではなく、対象言語やプロジェクト構成に合わせてビルド手順を整える必要があります。特にC#、Java、Goなどでは、ビルドが通らなければ分析精度や実行成否に影響します。
まず何を確認すべきか
自社やチームで同様の対応をするなら、最初に確認すべきことは明確です。
まず、対象リポジトリでCodeQLが既に有効か、default setupかadvanced setupかを確認してください。次に、.github/workflows/codeql.ymlがある場合は、push、pull_request、schedule、workflow_dispatchの設定を見ます。そのうえで、対象言語、ビルド手順、security-events: write権限、Actions使用量、PRチェックの扱いを確認します。
CodeQLは、導入しただけではセキュリティ品質を上げられません。PRで検出されたアラートを誰が確認し、どの重大度から直し、例外をどう記録するかまで決めて初めて、開発フローの中で機能します。今回の更新は、CodeQLを「手動でたまに回すツール」から「mainブランチを守る継続的なセキュリティチェック」へ戻すための実践例として捉えるとよいでしょう。
コメント