コンパイル済み言語の CodeQL ワークフローを構成する

CodeQL 分析ワークフローとコンパイル型言語について

GitHub がリポジトリに対して code scanning を実行できるようにするには、GitHub Actions ワークフローをリポジトリに追加します。 CodeQL code scanning では、CodeQL 分析ワークフローを追加できます。詳しくは、「リポジトリの code scanning を構成する」を参照してください。

通常、code scanning の既定のワークフローファイルを編集する必要はありません。ただし、必要な場合にはワークフローを編集して設定の一部をカスタマイズできます。たとえば、GitHub の CodeQL 分析ワークフローを編集すると、スキャンの頻度、スキャンする言語やディレクトリ、CodeQL code scanning を使ったコード内での検索対象を指定できます。コードのコンパイルに特定のコマンドセットを使う場合にも、CodeQL 分析ワークフローの編集が必要となる場合があります。code scanning の構成とワークフローファイルの編集に関する一般的な情報については、「code scanning のカスタマイズ」と「GitHub Actions について」を参照してください。

CodeQL の autobuild について

Code scanning は、1 つ以上のデータベースに対してクエリを実行することにより機能します。各データベースには、リポジトリにあるすべてのコードを 1 つの言語で表わしたものが含まれています。コンパイル型言語の C/C++、C#、Java では、このデータベースを生成するプロセスに、コードのビルドとデータの抽出が含まれています。これらの言語では、CodeQL は、ビルドされたリポジトリ内のソースファイルを分析します。これらの言語の場合は、autobuild を無効にし、その代わりにカスタムビルドコマンドによってビルドされたファイルのみを分析するためにこれらのカスタムコマンドを使用できます。

サポートされているコンパイル言語の場合、CodeQL 分析ワークフローの autobuild アクションを使ってコードをビルドできます。これにより、C/C++、C#、Java の明示的なビルドコマンドを指定する必要がなくなります。

ワークフローで language マトリックスを使っている場合、autobuild はマトリックスに列記された各コンパイル型言語のビルドを試行します。マトリックスがない場合、autobuild は、サポートされているコンパイル型言語で、リポジトリ内のソースファイルの数が最も多いもののビルドを試みます。 Go を除いて、明示的にビルドコマンドを使用しない限り、リポジトリにある他のコンパイル型言語の解析は失敗します。

注: 必要なソフトウェアをセルフホステッドランナーにインストールする必要があります。セルフホステッドランナーの詳細については、「自分のランナーをホストする」を参照してください。

C/C++

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows、macOS、Linux
ビルドシステム	Windows: MSbuild スクリプトと build スクリプト Linux と macOS: Autoconf、Make、CMake、qmake、 Meson、Waf、SCons、Linux Kbuild、build の各スクリプト

autobuild ステップの動作は、抽出を実行するオペレーティングシステムによって異なります。 Windows の autobuild ステップでは、以下の方法を使って C/C++ に適したビルド方法の自動検出が試みられます。

ルートに最も近いソリューション (.sln) またはプロジェクト (.vcxproj) ファイルで MSBuild.exe を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクトファイルを検出した場合、それらすべてのビルドが試みられます。
ビルドスクリプトのように見えるスクリプト、つまり build.bat、build.cmd、build.exe を、この順番で呼び出します。

Linux と macOS の autobuild ステップでは、リポジトリ内にあるファイルが確認されて、使われているビルドシステムが特定されます。

ルートディレクトリでビルドシステムを探します。
何も見つからない場合は、C/C++ のビルドシステムで一意のディレクトリをサブディレクトリで検索します。
適切なコマンドを実行してシステムを設定します。

C#

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows と Linux
ビルドシステム	.NET と MSbuild、およびビルドスクリプト

autobuild プロセスは、次の方法を使って C# に適したビルド方法の自動検出を試みます。

ルートに最も近いソリューション (.sln) またはプロジェクト (.csproj) ファイルで dotnet build を呼び出します。
ルートに最も近いソリューションまたはプロジェクトファイルで、MSbuild (Linux) または MSBuild.exe (Windows) を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクトファイルを検出した場合、それらすべてのビルドが試みられます。
ビルドスクリプトのように見えるスクリプト、つまり build と build.sh (Linux の場合、この順序で) または build.bat、build.cmd、and build.exe (Windows の場合、この順序で) を呼び出します。

Java

サポートされているシステムの種類	システム名
オペレーティングシステム	Windows、macOS、Linux (制限なし)
ビルドシステム	Gradle、Maven、Ant

autobuild プロセスは、この戦略を適用して、Java コードベース用のビルドシステムの特定を試みます。

ルートディレクトリでビルドファイルを検索します。 Gradle、Maven、Ant の各ビルドファイルを確認します。
最初に見つかったビルドファイルを実行します。 Gradle ファイルと Maven ファイルの両方が存在する場合は、Gradle ファイルが使用されます。
それ以外の場合は、ルートディレクトリの直接サブディレクトリ内でビルドファイルを検索します。 1 つのサブディレクトリにのみビルドファイルが含まれている場合は、そのサブディレクトリで識別された最初のファイルを実行します（1 と同じ環境設定を使用）。複数のサブディレクトリにビルドファイルが含まれている場合は、エラーを報告します。

コンパイル言語のビルドステップを追加する

autobuild が失敗した場合、または autobuild プロセスによってビルドされたものとは異なるソースファイルのセットを分析する場合は、ワークフローから autobuild ステップを削除し、ビルドステップを手動で追加する必要があります。 C/C++、C#、Go、Java プロジェクトの場合、CodeQL では、指定したビルドステップによってビルドされたソースコードを分析します。ワークフローファイルの編集方法については、「code scanning のカスタマイズ」を参照してください。

autobuild ステップを削除したら、run ステップをコメント解除して、リポジトリに適したビルドコマンドを追加します。ワークフローの run ステップでは、オペレーティングシステムのシェルを使ってコマンドラインプログラムが実行されます。これらのコマンドを変更し、別のコマンドを追加してビルドプロセスをカスタマイズできます。

- run: |
    make bootstrap
    make release

run キーワードについて詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

リポジトリに複数のコンパイル済み言語が含まれている場合は、言語固有のビルドコマンドを指定できます。たとえば、リポジトリに C/C++、C#、Java が含まれていて、autobuild によって C/C++ と C# は正しくビルドされるが、Java のビルドは失敗する場合は、ワークフローの init ステップの後で次の構成を使用できます。これにより、C/C++ と C# には autobuild をそのまま使用しつつ、Java のビルドステップを指定します。

- if: matrix.language == 'cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v2

- if: matrix.language == 'java'
  name: Build Java
  run: |
    make bootstrap
    make release

if 条件について詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

autobuild でコードがビルドされない理由に関するヒントとテクニックについては、「CodeQL ワークフローのトラブルシューティング」を参照してください。

コンパイル言語にマニュアルのビルドステップを追加しても、リポジトリで依然としてcode scanningが動作しない場合は、エンタープライズ所有者にお問い合わせください。